Hướng Dẫn Sử Dụng Apiframe Trong n8n (Từng Bước)

Trong hướng dẫn này, bạn sẽ học cách kết nối Apiframe với n8n để bạn có thể tạo hình ảnh AI (hoặc video, nhạc, v.v.) từ bất kỳ workflow nào.

Chúng ta sẽ cùng tìm hiểu:

Chúng ta sẽ xây gì
Yêu cầu trước khi bắt đầu
Tạo thông tin xác thực Apiframe trong n8n
Workflow 1 - Tạo hình ảnh đơn giản bằng /imagine
Workflow 2 - Kiểm tra kết quả định kỳ với /fetch
Workflow 3 - Khuyến nghị: Dùng webhook để nhận kết quả theo thời gian thực
Mở rộng mẫu này cho các endpoint khác của Apiframe

Tất cả ví dụ sẽ dùng endpoint Midjourney /imagine nhưng cùng một mẫu này hoạt động với hầu hết các endpoint và mô hình khác.

I. Chúng ta sẽ xây dựng gì

Chúng ta sẽ xây hai tích hợp n8n nhỏ:

Tạo hình ảnh theo yêu cầu
- Trigger: Thủ công, Webhook, Google Sheet, bất cứ thứ gì
- HTTP Request: POST https://api.apiframe.pro/imagine
- Nhận lại một task_id Bạn có thể lưu lại hoặc ghi log
Tự động lấy về hình ảnh cuối cùng
- Bằng cách gọi lặp lại Apiframe với /fetch cho đến khi tác vụ hoàn tất
- Hoặc (khuyến nghị) để Apiframe gọi n8n Webhook khi tác vụ hoàn tất

Khi URL hình ảnh đã về n8n, bạn có thể làm bất cứ điều gì: gửi chúng đến Slack, lưu chúng vào Airtable, Google Drive, v.v.

II. Điều kiện tiên quyết

Bạn sẽ cần:

Một tài khoản Apiframe và một API key. Bạn có thể lấy nó từ dashboard Apiframe của mình (hoặc Bấm vào đây). API key này sẽ được dùng để xác thực các request của chúng ta thông qua header Authorization .

Một instance n8n (tự host hoặc dùng bản cloud)
Hiểu biết cơ bản về các node trong n8n (HTTP Request, Webhook, Set, IF, v.v.). Node HTTP Request là cách tổng quát để gọi bất kỳ REST API nào trong n8n.

III. Tạo thông tin đăng nhập Apiframe trong n8n

Chúng ta sẽ cấu hình thông tin đăng nhập một lần, sau đó tái sử dụng trong tất cả các node HTTP Request.

Bước 1: Trong n8n, đi tới Credentials → Create credential.

Bước 2: Chọn Header Auth (hoặc "HTTP Header Auth", "API Key in Header" tùy theo phiên bản của bạn)

Bước 3: Cấu hình:
- Tên header: Authorization
- Giá trị: Apiframe API key của bạn (chính xác như hiển thị trong dashboard)

Bước 4: Đặt cho nó một tên như Apiframe Auth rồi lưu lại

Apiframe yêu cầu:

text
Authorization: YOUR_API_KEY
Content-Type: application/json

IV. Workflow 1 - Tạo ảnh cơ bản với /imagine

Chúng ta sẽ xây một workflow đơn giản:

💡

Manual Trigger → Set prompt → HTTP Request → Log task_id

1. Tạo workflow

Trong n8n, tạo một New workflow.
Thêm một Manual Trigger node.

2. Thêm một node "Set" cho prompt

Thêm một Set node sau Manual Trigger.
Trong Values → Add Field → String:
- Name: prompt
- Value: chẳng hạn như a cinematic photo of a cyberpunk city at night, ultra detailed, 4k
(Tuỳ chọn) Thêm một trường string khác:
- Name: aspect_ratio
- Value: 3:2

Bây giờ output JSON của node Set sẽ trông đại khái như sau:

json
{
  "prompt": "a cinematic photo of a cyberpunk city at night, ultra detailed, 4k",
  "aspect_ratio": "3:2"
}

3. Thêm node HTTP Request cho /imagine

Thêm một HTTP Request node sau node Set.
Cấu hình:
- Method: POST
- URL: https://api.apiframe.pro/imagine
- Với phần xác thực (authentication), chọn "Generic Credential type", sau đó "Header Auth", rồi chọn thông tin xác thực “Apiframe Auth” mà bạn đã tạo trước đó.
- Với phần body, bật "Send body", rồi thêm các trường: prompt, aspect_ratio, và tuỳ chọn webhook_url để dùng về sau.

Khi bạn chạy node này, Apiframe sẽ trả về một nội dung tương tự như:

json
{
  "task_id": "29e983ca-7e86-4017-a9e3-ef6fe9cd5f2a"
}

Điều này có nghĩa là tác vụ đang ở trạng thái queued/processing. Ảnh được tạo không đồng bộ; bạn sẽ không nhận được URL cuối cùng từ chính endpoint /imagine.

Bây giờ bạn có thể:

Log lại task_id
Lưu nó vào CSDL / Google Sheet
Truyền nó sang một workflow “Fetch”

V. Workflow 2 - Poll Apiframe với /fetch

Bây giờ hãy lấy các URL ảnh thực tế bằng endpoint /fetch.

Apiframe cung cấp một endpoint POST https://api.apiframe.pro/fetch nhận task_id và trả về hoặc là kết quả cuối cùng hoặc một phản hồi status: "processing".

Chúng ta sẽ làm một luồng tối giản kiểu “Chờ rồi Fetch”.

1. Thêm một node Wait

Sau node HTTP Request /imagine:

Thêm một node Wait.
Đặt nó chờ, ví dụ, 2–3 giây.

Điều này cho Apiframe đủ thời gian để hoàn tất việc tạo ảnh. Thời gian tạo phụ thuộc vào độ phức tạp của tác vụ và tải hệ thống.

2. Thêm node HTTP Request cho /fetch

Thêm một node HTTP Request nữa sau node Wait:

Method: POST
URL: https://api.apiframe.pro/fetch
Đối với phần xác thực, chọn "Generic Credential type", sau đó "Header Auth", rồi chọn “Apiframe Auth”, giống như trước đó.
Với phần body, bật "Send body", và chúng ta sẽ thêm task_id field

Đang xử lý (job vẫn đang chạy):

json
{
  "task_id": "29e983ca-7e86-4017-a9e3-ef6fe9cd5f2a",
  "task_type": "imagine",
  "status": "processing",
  "percentage": "40"
}

Hoàn tất (job xong, URL ảnh đã sẵn sàng):

json
{
  "task_id": "29e983ca-7e86-4017-a9e3-ef6fe9cd5f2a",
  "task_type": "imagine",
  "original_image_url": "https://.../grid.png",
  "image_urls": [
    "https://.../image1.png",
    "https://.../image2.png",
    "https://.../image3.png",
    "https://.../image4.png"
  ]
}

3. Xử lý trường hợp “vẫn đang xử lý”

Để setup nhanh khi dev, bạn có thể:

Chỉ cần chờ lâu hơn và fetch một lần.
Hoặc thêm một IF node đơn giản sau node Fetch:
- Điều kiện: status bằng "processing"
- Nếu “true”: rẽ nhánh sang một Wait + Fetch khác
- Nếu “false”: tiếp tục với logic cuối (Slack, Airtable, v.v.)

Trong môi trường production, Apiframe khuyến nghị dùng webhook thay vì polling để tránh request không cần thiết và nhận cập nhật tức thì.

Giờ chúng ta sẽ làm phần đó.

VI. Workflow 3 - Nhận kết quả bằng Webhook (khuyến nghị)

Đây là kiến trúc gọn gàng, “thời gian thực”:

Workflow A: Gửi yêu cầu tạo ảnh (kèm webhook_url và webhook_secret)
Workflow B: Nhận webhook từ Apiframe khi quá trình tạo ảnh hoàn tất

1. Tạo Workflow B - Webhook nhận kết quả

Tạo một New workflow trong n8n và đặt tên là Apiframe – Hình ảnh đã hoàn thành.
Thêm một nút Webhook Cấu hình nút Webhook:
- HTTP Method: POST
- Path: ví dụ như apiframe/midjourney-completed
- Response mode:
  - Ví dụ, chọn When Last Node Finishes (để bạn có thể trả dữ liệu về nếu muốn).

Sao chép Production URL – đây là giá trị chúng ta sẽ đặt cho webhook_url trong Apiframe.

2. Bảo mật webhook với "`webhook_secret"`

Apiframe cho phép bạn truyền một webhook_secret trong request /imagine; giá trị này sẽ được gửi trả lại dưới dạng header x-webhook-secret trên các cuộc gọi webhook.

Thêm một nút IF sau nút Webhook.
Trong nút IF, kiểm tra:
- Bên trái: Biểu thức như ={{ $json["headers"]["x-webhook-secret"] }}
- Điều kiện: equals
- Bên phải: secret của bạn, ví dụ my-super-secret
Nếu secret không khớp, hãy chuyển sang một nhánh chỉ kết thúc luôn (hoặc ghi log lần thử đó).

Điều này đảm bảo chỉ các webhook từ Apiframe mới được xử lý.

3. Truy cập các URL hình ảnh trong payload của webhook

Phần body của webhook sẽ giống với payload “completed” đã được trình bày trước đó:

json
{
  "task_id": "29e983ca-7e86-4017-a9e3-ef6fe9cd5f2a",
  "task_type": "imagine",
  "original_image_url": "https://.../grid.png",
  "image_urls": [
    "https://.../image1.png",
    "https://.../image2.png",
    "https://.../image3.png",
    "https://.../image4.png"
  ]
}

Bạn có thể truy cập các URL hình ảnh, rồi truyền chúng vào:

Node Slack (gửi một tin nhắn kèm URL)
Airtable / Notion (lưu trữ URL)
HTTP Request (đẩy sang backend của ứng dụng bạn)

4. Cập nhật Workflow A để dùng webhook

Quay lại Workflow A (workflow đang gọi /imagine) và chỉnh sửa body của node HTTP Request để bao gồm:

webhook_url
webhook_secret

Ví dụ JSON body trong node HTTP Request:

json
{
  "prompt": "a cinematic photo of a cyberpunk city at night, ultra detailed, 4k",
  "aspect_ratio": "3:2",
  "webhook_url": "https://your-n8n-domain.com/webhook/apiframe/midjourney-completed",
  "webhook_secret": "my-super-secret"
}

Giờ luồng xử lý sẽ là:

Workflow A → /imagine với webhook_url + webhook_secret
Apiframe tạo ảnh ở chế độ nền
Khi xong, Apiframe sẽ gọi Webhook (Workflow B) của bạn kèm theo các URL cuối cùng
Workflow B xử lý chúng và đẩy chúng đến bất kỳ nơi nào bạn muốn

Không cần polling, không cần thêm HTTP request – chỉ dựa trên sự kiện (event-driven).

VII. Mở rộng mẫu này cho các endpoint khác của Apiframe

Điểm hay là: khi bạn đã kết nối n8n → Apiframe một lần, bạn có thể tái sử dụng cùng một mẫu cho mọi thứ.

Một vài ý tưởng:

Variations: đổi URL thành https://api.apiframe.pro/variations và gửi kèm task_id + prompt mới.
Upscales: cùng kiểu xác thực, chỉ khác endpoint/body.
Faceswap: gửi hai URL ảnh (nguồn & đích) đến endpoint faceswap .
Describe: xây một workflow n8n nơi bạn chỉ cần thả vào một URL ảnh và Apiframe sẽ trả về prompt mô tả ảnh đó.
Các loại media khác: Flux, Ideogram, Luma, Suno, v.v. đều tuân theo cùng một mẫu REST: POST với JSON, bao gồm webhook_url + webhook_secret nếu bạn muốn sử dụng webhook.

Mỗi cái trong số này thực chất chỉ là một node HTTP Request khác (hoặc hai node, nếu bạn cũng dùng /fetch) dùng chung cùng thông tin xác thực “Apiframe Auth”.

VIII. Tổng kết

Giờ bạn đã có:

Một workflow /imagine cơ bản để kích hoạt Midjourney thông qua Apiframe trong n8n
Một thiết lập polling sử dụng /fetch cho các thử nghiệm nhanh
Một kiến trúc dựa trên webhook cho các pipeline thời gian thực, đạt chuẩn production

I. Chúng ta sẽ xây dựng gì

II. Điều kiện tiên quyết

III. Tạo thông tin đăng nhập Apiframe trong n8n

IV. Workflow 1 - Tạo ảnh cơ bản với /imagine

1. Tạo workflow

2. Thêm một node "Set" cho prompt

3. Thêm node HTTP Request cho /imagine

V. Workflow 2 - Poll Apiframe với /fetch

1. Thêm một node Wait

2. Thêm node HTTP Request cho /fetch

3. Xử lý trường hợp “vẫn đang xử lý”

VI. Workflow 3 - Nhận kết quả bằng Webhook (khuyến nghị)

1. Tạo Workflow B - Webhook nhận kết quả

2. Bảo mật webhook với "webhook_secret"

3. Truy cập các URL hình ảnh trong payload của webhook

4. Cập nhật Workflow A để dùng webhook

VII. Mở rộng mẫu này cho các endpoint khác của Apiframe

VIII. Tổng kết

Tiếp tục học

Bắt Đầu Với Apiframe

Sẵn sàng bắt đầu?

2. Bảo mật webhook với "`webhook_secret"`