API tạo ảnh bất đồng bộ: Jobs, Polling, Webhooks và Retries

API tạo ảnh bất đồng bộ (async) cho phép bạn gửi yêu cầu tạo ảnh, nhận lại mã định danh job ngay lập tức và truy xuất ảnh đã hoàn thành sau đó thay vì phải giữ kết nối HTTP mở. Hướng dẫn này bao gồm vòng đời của job, khi nào nên sử dụng polling (thăm dò) so với webhook, và cách thiết kế cơ chế thử lại (retry) để một job chậm hoặc thất bại không làm ảnh hưởng đến trải nghiệm sản phẩm của bạn.

Những điểm chính cần lưu ý

• Tạo ảnh dựa trên mô hình job, không phải request-response, vì độ trễ khi tạo (từ vài giây đến hàng chục giây) khiến việc giữ kết nối đồng bộ trở nên thiếu ổn định.
• Polling dễ xây dựng và gỡ lỗi hơn; webhook giúp giảm độ trễ và lưu lượng request nhưng yêu cầu một endpoint công khai, xác thực chữ ký và xử lý trùng lặp (idempotent).
• Logic thử lại cần phân biệt giữa lỗi gửi yêu cầu, job bị treo và webhook bị bỏ lỡ; mỗi trường hợp cần một lộ trình khôi phục khác nhau.
• Tên endpoint, tên trường và cấu trúc payload của webhook chính xác sẽ khác nhau tùy theo nhà cung cấp và giao diện API của TokenLab. Luôn xác nhận các thông số kỹ thuật hiện tại tại docs.tokenlab.sh trước khi triển khai.

Tại sao các API tạo ảnh lại là bất đồng bộ?

Các API hoàn thiện văn bản thường có thể trả về phản hồi trên cùng một kết nối vì việc tạo token đủ nhanh để truyền phát (stream). Các mô hình tạo ảnh, dù dựa trên diffusion hay tự hồi quy (autoregressive), thường mất nhiều thời gian hơn và có độ trễ thay đổi tùy thuộc vào độ phân giải, lựa chọn mô hình và độ sâu của hàng đợi. Việc giữ một yêu cầu HTTP đồng bộ mở trong hàng chục giây rất mong manh: timeout phía client, giới hạn thời gian chờ của load balancer và mất kết nối mạng di động đều làm tăng nguy cơ mất kết quả đã hoàn thành mà bạn đã trả phí để tạo.

Mô hình tiêu chuẩn được sử dụng bởi các nhà cung cấp dịch vụ tạo ảnh là mô hình job: bạn gửi yêu cầu và nhận được mã định danh job cùng trạng thái ban đầu (thường là queued hoặc processing). Sau đó, bạn có thể poll một endpoint trạng thái hoặc nhận thông báo qua webhook khi job đạt đến trạng thái cuối cùng, rồi lấy URL ảnh cuối cùng hoặc dữ liệu nhị phân trong một cuộc gọi riêng biệt.

TokenLab cung cấp quyền truy cập vào nhiều mô hình ảnh, bao gồm họ Nano Banana 2, Nano Banana Pro và Nano Banana 2 Lite, GPT Image 2, Reve 2.0 và MAI-Image-2.5, thông qua một giao diện API duy nhất. Xem danh mục mô hình ảnh để biết danh sách hiện tại và hướng dẫn về các tác vụ tạo ảnh bất đồng bộ để biết hành vi endpoint job cụ thể của TokenLab. Mô hình chung dưới đây áp dụng bất kể bạn gọi mô hình nào, nhưng tên trường và giá trị trạng thái chính xác được ghi lại tại docs.tokenlab.sh và nên được xác minh tại đó thay vì giả định từ bài viết này.

Vòng đời của Job: Gửi, Poll, Truy xuất

Ở cấp độ khái niệm, một job tạo ảnh bất đồng bộ có ba giai đoạn:

1. Gửi (Submit): POST một prompt và các tham số, nhận lại ID job và trạng thái ban đầu.
2. Kiểm tra trạng thái (Check status): hoặc poll một endpoint GET sử dụng ID job, hoặc chờ sự kiện webhook.
3. Truy xuất kết quả (Retrieve output): khi trạng thái là kết thúc (thành công hoặc thất bại), lấy (các) URL ảnh hoặc chi tiết lỗi.

Dưới đây là mô hình polling minh họa bằng Python. Hãy coi các đường dẫn endpoint và tên trường là các phần giữ chỗ; hãy xác nhận cấu trúc endpoint job của TokenLab hiện tại trong tài liệu API trước khi sử dụng trong môi trường production.

import time
import requests

API_BASE = "https://api.tokenlab.sh/v1"  # xác minh URL cơ sở hiện tại trong docs.tokenlab.sh
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def submit_image_job(prompt, model="nano-banana-2"):
    resp = requests.post(
        f"{API_BASE}/images/jobs",
        headers=HEADERS,
        json={"prompt": prompt, "model": model, "idempotency_key": generate_key()},
    )
    resp.raise_for_status()
    return resp.json()["job_id"]

def poll_job(job_id, max_wait_seconds=120, interval=2, backoff=1.5):
    waited = 0
    while waited < max_wait_seconds:
        resp = requests.get(f"{API_BASE}/images/jobs/{job_id}", headers=HEADERS)
        resp.raise_for_status()
        data = resp.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
        waited += interval
        interval = min(interval * backoff, 15)
    raise TimeoutError(f"Job {job_id} did not complete within {max_wait_seconds}s")

job_id = submit_image_job("a studio product shot on white background")
result = poll_job(job_id)
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
else:
    print("job failed:", result.get("error"))

idempotency_key trong lệnh gọi submit rất quan trọng: nếu xảy ra lỗi mạng sau khi job được tạo nhưng trước khi client của bạn nhận được ID job, việc thử lại lệnh gọi submit với cùng một key sẽ trả về job hiện có thay vì tạo ra một bản sao tạo ảnh khác. Hãy xác nhận xem endpoint job của TokenLab có hỗ trợ idempotency key hay không trong tài liệu hiện tại, vì đây là một mô hình phổ biến nhưng không phải là mặc định ở tất cả các nhà cung cấp.

Polling so với Webhook: Đánh đổi

Cả hai cách tiếp cận đều hợp lệ; lựa chọn phù hợp phụ thuộc vào mô hình lưu lượng truy cập và cơ sở hạ tầng của bạn.

Polling đơn giản hơn để triển khai và kiểm tra cục bộ, không yêu cầu endpoint công khai và hoạt động tốt cho các khối lượng công việc thấp hoặc theo lô, nơi mà độ trễ thêm vài giây không thành vấn đề. Nhược điểm của nó là mức độ trễ tối thiểu bằng khoảng thời gian poll của bạn và lưu lượng yêu cầu không cần thiết nếu bạn poll quá thường xuyên trên các job chạy lâu.

Webhook đẩy thông báo đến máy chủ của bạn khi trạng thái job thay đổi, giúp giảm độ trễ và cắt giảm các cuộc gọi kiểm tra trạng thái lãng phí. Chi phí là về mặt vận hành: bạn cần một endpoint HTTPS có thể truy cập công khai, xác thực chữ ký để xác nhận payload thực sự đến từ nhà cung cấp và xử lý các trường hợp gửi trùng lặp hoặc sai thứ tự.

Tài liệu về các sự kiện webhook của OpenAI tham chiếu cấu trúc chung của mô hình này cho các hoạt động bất đồng bộ: endpoint của bạn nhận được một sự kiện với loại và mã định danh đối tượng, và thực hành được khuyến nghị là coi payload webhook như một thông báo để đi lấy trạng thái hiện tại của tài nguyên thông qua API, thay vì tin tưởng nội dung webhook là nguồn sự thật cuối cùng. Mô hình "kéo sau khi đẩy" (pull-after-push) này rất đáng áp dụng bất kể bạn đang tích hợp nhà cung cấp ảnh nào, vì nó bảo vệ bạn nếu payload webhook bị cắt bớt, trì hoãn hoặc gửi nhiều lần.

Triển khai Webhook an toàn

Nếu bạn chọn webhook để hoàn thành job tạo ảnh, các thực hành sau đây sẽ giảm nguy cơ xảy ra lỗi âm thầm:

• Xác minh chữ ký trên mọi yêu cầu webhook đến trước khi xử lý. Từ chối bất cứ thứ gì không khớp và ghi lại các lần từ chối riêng biệt với lưu lượng truy cập bình thường để bạn có thể phát hiện nhanh một secret bị cấu hình sai.
• Phản hồi nhanh, xử lý sau. Xác nhận webhook với trạng thái 200 ngay khi bạn đã xác thực nó, sau đó chuyển công việc thực tế (lấy ảnh, ghi vào bộ lưu trữ, thông báo cho người dùng) sang một job hoặc hàng đợi nền. Các nhà cung cấp thường thử lại việc gửi webhook nếu họ không nhận được phản hồi 2xx kịp thời, điều này có thể gây ra xử lý trùng lặp nếu trình xử lý của bạn chậm và đồng bộ.
• Khử trùng lặp theo ID job. Lưu trữ các ID job đã xử lý (hoặc mã băm của sự kiện) để việc gửi lại không tạo ra thông báo hoặc xử lý lại việc ghi tệp.
• Lấy lại tài nguyên bằng cách sử dụng ID job từ payload webhook thay vì tin tưởng các URL đầu ra được nhúng là kết quả cuối cùng, phù hợp với mô hình pull-after-push đã mô tả ở trên.

Một bản phác thảo trình xử lý tối thiểu:

from flask import Flask, request, abort

app = Flask(__name__)
processed_job_ids = set()  # sử dụng kho lưu trữ thực tế trong production

@app.route("/webhooks/image-jobs", methods=["POST"])
def handle_webhook():
    if not verify_signature(request):
        abort(401)

    event = request.get_json()
    job_id = event.get("job_id") or event.get("data", {}).get("id")
    if job_id in processed_job_ids:
        return "", 200  # đã xử lý, xác nhận và bỏ qua

    enqueue_background_task("fetch_and_store_image", job_id)
    processed_job_ids.add(job_id)
    return "", 200

Xác minh tên sự kiện webhook chính xác, cấu trúc payload và header chữ ký được sử dụng để hoàn thành job tạo ảnh dựa trên tài liệu của nhà cung cấp hiện tại và riêng biệt với hỗ trợ webhook của TokenLab như được mô tả tại docs.tokenlab.sh, vì các chi tiết này là đặc thù của nhà cung cấp và có thể thay đổi.

Thiết kế thử lại (Retry): Ba loại lỗi

Các job tạo ảnh bất đồng bộ thất bại theo ba cách riêng biệt và mỗi cách cần cách xử lý riêng:

1. Lỗi gửi (Submission failures): POST để tạo job trả về 4xx hoặc 5xx. Đối với lỗi 5xx và lỗi mạng, hãy thử lại với exponential backoff và jitter, sử dụng lại cùng một idempotency key để bạn không tạo ra các job trùng lặp. Đối với lỗi 4xx (prompt xấu, mô hình không hợp lệ, vượt quá hạn ngạch), việc thử lại mà không thay đổi yêu cầu sẽ chỉ thất bại lần nữa; hãy hiển thị lỗi cho người gọi.
2. Job bị treo (Stuck jobs): một job duy trì ở trạng thái không kết thúc lâu hơn thời gian tạo dự kiến. Hãy đặt ngưỡng chờ tối đa cho mỗi mô hình (thời gian tạo thay đổi tùy theo mô hình và độ phân giải) và coi các job vượt quá ngưỡng này là thất bại đối với mục đích ứng dụng của bạn, ngay cả khi nhà cung cấp chưa chính thức đánh dấu chúng là thất bại. Hãy ghi lại các lỗi này riêng biệt, vì tỷ lệ job bị treo tăng cao thường báo hiệu sự cố từ phía nhà cung cấp.
3. Webhook bị bỏ lỡ (Missed webhook deliveries): endpoint của bạn bị sập hoặc việc gửi bị hủy và không có sự kiện nào đến. Đây là lý do tại sao việc dự phòng bằng polling vẫn đáng giá ngay cả trong thiết kế ưu tiên webhook: một đợt quét định kỳ kiểm tra trạng thái của bất kỳ job nào cũ hơn vài phút mà chưa có trạng thái kết thúc sẽ bắt được các job mà webhook của chúng bị lỗi âm thầm không đến được.

Danh sách kiểm tra quyết định

Sử dụng danh sách kiểm tra này khi quyết định cách kết nối việc hoàn thành job cho tính năng tạo ảnh.

Kịch bản	Cách tiếp cận khuyến nghị	Tại sao
Khối lượng thấp, công cụ nội bộ hoặc tập lệnh batch	Polling	Dễ xây dựng nhất; không cần endpoint công khai
Tính năng hướng người dùng nơi độ trễ quan trọng	Webhook, với dự phòng polling	Độ trễ thấp hơn; dự phòng bắt được các lần gửi bị bỏ lỡ
Khối lượng job cao (hàng ngàn/ngày)	Webhook	Tránh lưu lượng yêu cầu kiểm tra trạng thái quá mức
Không có khả năng hiển thị endpoint HTTPS công khai	Polling	Webhook yêu cầu một bộ thu có thể truy cập được
Cần ngăn chặn trùng lặp nghiêm ngặt	Idempotency keys khi gửi, khử trùng lặp theo ID job khi nhận	Bảo vệ chống lại các lần gửi thử lại và gửi webhook trùng lặp
Nhiều mô hình ảnh trong một pipeline	Chuẩn hóa trạng thái job và xử lý lỗi trong lớp của riêng bạn	Các nhà cung cấp cơ bản (xem so sánh mô hình ảnh) không chia sẻ các phân loại trạng thái giống hệt nhau

Hạn chế

Bài viết này mô tả một mô hình chung cho các API job ảnh bất đồng bộ và không khẳng định các đường dẫn endpoint, tên trường, giá trị timeout hoặc tên sự kiện webhook chính xác cho TokenLab hoặc cho bất kỳ nhà cung cấp mô hình cơ bản cụ thể nào ngoài những gì đã được trích dẫn ở trên. Từ vựng trạng thái job, header retry-after và các lược đồ chữ ký webhook thay đổi giữa các nhà cung cấp và có thể thay đổi theo thời gian; hãy coi mã trong bài viết này là minh họa, không phải mã production để sao chép-dán, và xác nhận các cấu trúc yêu cầu và phản hồi hiện tại tại docs.tokenlab.sh trước khi triển khai. Bài viết này không bao gồm giá cả, giới hạn tốc độ hoặc đảm bảo thông lượng cho bất kỳ mô hình cụ thể nào.

Câu hỏi thường gặp

Tôi có nên luôn sử dụng webhook thay vì polling không? Không. Webhook giảm độ trễ và lưu lượng yêu cầu với chi phí vận hành cao hơn. Đối với các trường hợp sử dụng khối lượng thấp hoặc nội bộ, polling thường là lựa chọn đơn giản và đáng tin cậy tương đương. Nhiều hệ thống production sử dụng webhook làm đường dẫn chính với một đợt quét polling định kỳ làm dự phòng.

Làm thế nào để tránh tạo ảnh trùng lặp khi thử lại? Sử dụng idempotency key trên yêu cầu gửi job để một lệnh POST thử lại sau khi lỗi mạng trả về job hiện có thay vì tạo một job mới. Xác nhận xem endpoint tạo job của nhà cung cấp của bạn có hỗ trợ điều này không trước khi dựa vào nó.

Điều gì xảy ra nếu endpoint webhook của tôi bị sập khi job hoàn thành? Hành vi phụ thuộc vào nhà cung cấp; một số thử lại việc gửi trong một khoảng thời gian, những nhà cung cấp khác không đảm bảo gửi lại. Một đợt quét polling định kỳ cho các job cũ hơn vài phút mà không có trạng thái kết thúc là một biện pháp bảo vệ thiết thực bất kể chính sách thử lại của nhà cung cấp là gì.

Nếu bạn đang xây dựng tính năng tạo ảnh và muốn so sánh quyền truy cập dựa trên job trên nhiều mô hình trong một API, hãy xem lại danh mục mô hình ảnh và hướng dẫn về các tác vụ tạo ảnh bất đồng bộ, sau đó Bắt đầu với tài liệu API của TokenLab để xác nhận các chi tiết endpoint và webhook hiện tại cho bản dựng của bạn.