APIMaster.ai
Tài liệu APIMaster.ai
Quick startAPIMaster.aiMarketplace

APIMaster Webhook Tác vụ Bất đồng bộ

Nhận thông báo hoàn thành và thất bại có chữ ký cho Seedance, tác vụ video và hình ảnh bất đồng bộ, với cơ chế thử lại, lịch sử gửi và phương án dự phòng polling.

Webhook tác vụ bất đồng bộ APIMaster

Sử dụng webhook làm cơ chế thông báo chính cho việc tạo nội dung bất đồng bộ, và giữ polling làm phương án dự phòng. APIMaster gửi một yêu cầu HTTPS POST có chữ ký khi một tác vụ được theo dõi hoàn thành hoặc thất bại. Thông báo độc lập với nhà cung cấp tạo nội dung và sử dụng ID tác vụ APIMaster của bạn.

Mô hình và endpoint được hỗ trợ

Seedance bao gồm tất cả bốn mô hình: seedance-2.0, seedance-2.5, seedance-2.0-fast và seedance-2.0-mini. Sử dụng POST /v1/videos/generations hoặc POST /v1/video/generations tương thích.

Thông báo tác vụ video cũng hỗ trợ MiniMax-H3, Kling Omni / Motion Control, Grok Imagine Video và Sora. Các luồng công việc hình ảnh GPT Image 2 / 2.5 và Gemini được hỗ trợ sử dụng /v1/images/generations/async hoặc /v1/images/edits/async được hỗ trợ; Midjourney v8.2 / Niji 7 sử dụng /v1/midjourney/generations. Tính khả dụng của tuyến đường và tham số tạo nội dung vẫn tuân theo hướng dẫn của từng mô hình. Tạo Seedream và Grok đồng bộ, phát trực tuyến chat và xem xét tài sản Seedance không thuộc hợp đồng webhook tạo nội dung này.

Kiểm tra GET /v1/webhook-capabilities?model=seedance-2.0-fast để biết điều kiện áp dụng của mô hình. Sử dụng một endpoint gửi bất đồng bộ được hỗ trợ; điều kiện áp dụng không có nghĩa là mọi thao tác hình ảnh hoặc mọi bí danh mô hình đều hỗ trợ tạo nội dung bất đồng bộ.

Đăng ký và xác minh một endpoint

Sử dụng khóa API của bạn trong Authorization: Bearer YOUR_API_KEY. Một khóa API có thể quản lý các endpoint và sự kiện thuộc về tài khoản của nó. Giữ nó trên máy chủ của bạn.

curl --fail-with-body "https://apimaster.ai/v1/webhook-endpoints" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.example/webhooks/apimaster"}'

Phản hồi chứa endpoint.id, endpoint.key_id và signing_secret. Lưu trữ bí mật ký an toàn: nó chỉ được trả về một lần. Nó tách biệt với khóa API của bạn và không thể ủy quyền cho việc tạo nội dung hoặc tải xuống. URL phải là một endpoint HTTPS có thể truy cập công khai trên cổng 443. Địa chỉ riêng tư và chuyển hướng bị từ chối. Tối đa 20 endpoint được phép cho mỗi tài khoản; URL là bất biến, vì vậy hãy tạo và xác minh một endpoint mới khi thay đổi điểm đến.

Sau khi cấu hình máy nhận của bạn, hãy xác minh quyền sở hữu:

curl --fail-with-body -X POST "https://apimaster.ai/v1/webhook-endpoints/whep_example/verify" \
  -H "Authorization: Bearer YOUR_API_KEY"

APIMaster gửi một sự kiện webhook.endpoint_verification có chữ ký chứa data.challenge. Trả về HTTP 200 với {"challenge":"THE_RECEIVED_CHALLENGE"} trong vòng 10 giây. Một yêu cầu tạo nội dung tham chiếu đến một endpoint chưa được xác minh, đã tạm dừng hoặc thuộc tài khoản khác sẽ bị từ chối trước khi gửi.

Thời gian chờ tổng cộng của yêu cầu HTTP là 10 giây, bao gồm DNS, kết nối và TLS. Tiêu đề phản hồi phải đến trong vòng 8 giây sau khi gửi yêu cầu. Lưu sự kiện bền vững rồi xác nhận ngay.

Gửi một tác vụ với thông báo

curl --fail-with-body "https://apimaster.ai/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"seedance-2.5",
    "prompt":"A paper boat floating on a calm pond, slow camera movement.",
    "duration":4,
    "resolution":"480p",
    "aspect_ratio":"16:9",
    "notifications":{
      "webhook":{
        "endpoint_id":"whep_example",
        "events":["task.completed","task.failed"]
      }
    },
    "client_reference_id":"order_123"
  }'

Thay thế ID mô hình bằng bất kỳ ID Seedance nào trong bốn ID trong khi vẫn giữ các tham số được hỗ trợ riêng của nó. Lưu ID tác vụ từ phản hồi tạo thông thường. client_reference_id là một tham chiếu nghiệp vụ tùy chọn tối đa 128 byte; nó không phải là khóa idempotency khi gửi. Không kết hợp notifications với các tham số nhà cung cấp cũ webhook hoặc callback_url.

Đối với chỉnh sửa hình ảnh multipart được hỗ trợ, gửi notifications dưới dạng một trường form chuỗi JSON và client_reference_id dưới dạng một trường form riêng biệt:

curl --fail-with-body "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Turn the reference into a watercolor illustration" \
  -F "image=@reference.png" \
  -F 'notifications={"webhook":{"endpoint_id":"whep_example","events":["task.completed","task.failed"]}}' \
  -F "client_reference_id=image_order_123"

Không có endpoint mặc định trên toàn tài khoản trong phiên bản này: tham chiếu một endpoint trong mỗi yêu cầu tác vụ. Webhook có thể đến trước phản hồi gửi của bạn. Hãy lưu trữ chúng ngay cả khi ứng dụng của bạn chưa lưu ID tác vụ được trả về. Một số luồng công việc hình ảnh bất đồng bộ bao bọc việc tạo nội dung upstream đồng bộ, vì vậy bản thân việc gửi vẫn có thể tốn thời gian.

Tải trọng thành công và thất bại

Một thông báo thành công chứa ID tác vụ công khai và một liên kết video đã xác thực:

{
  "id":"evt_example",
  "type":"task.completed",
  "api_version":"2026-10-03",
  "created_at":1791014400,
  "data":{
    "task_id":"task_example",
    "model":"seedance-2.5",
    "kind":"video",
    "status":"completed",
    "client_reference_id":"order_123",
    "completed_at":1791014400,
    "task_url":"https://apimaster.ai/v1/videos/task_example",
    "result":{
      "outputs":[{
        "output_id":"0",
        "type":"video",
        "url":"https://apimaster.ai/v1/videos/task_example/content",
        "authentication":"bearer",
        "expires_at":null
      }]
    },
    "error":null
  }
}

Thất bại sử dụng phong bì tương tự với type: "task.failed", data.status: "failed", data.result: null và một đối tượng lỗi:

{
  "code":"generation_failed",
  "message":"The generation task failed. Query the task for details."
}

Cả lỗi được nhà cung cấp xác nhận và thời gian chờ tác vụ cổng đều có thể tạo ra sự kiện thất bại. Một yêu cầu tạo bị từ chối trước khi tác vụ được chấp nhận sẽ không tạo ra sự kiện tác vụ. Gửi thông báo thất bại không thay đổi trạng thái tạo nội dung hoặc chạy lại việc tạo nội dung. Sự kiện không xác nhận rằng việc đối chiếu thanh toán đã hoàn tất.

Đối với hình ảnh, kind là image và outputs chứa tất cả đầu ra hình ảnh có sẵn. Sự kiện tác vụ con Midjourney bao gồm batch_id; bạn có thể đăng ký thêm batch.completed để nhận một bản tóm tắt hàng loạt sau khi tất cả các tác vụ con hoàn thành. Trạng thái của nó là completed, partial_failure hoặc failed, với số lượng trong data.summary. Hoàn thành hàng loạt không phải lúc nào cũng có nghĩa là mọi tác vụ con đều thành công.

Tải xuống URL đầu ra bằng một khóa API thuộc về tài khoản của tác vụ. Lưu trữ phương tiện được tạo ngay lập tức. expires_at: null có nghĩa là không có thời gian hết hạn đảm bảo được cung cấp, không phải lưu trữ vĩnh viễn; một lần tải xuống sau này có thể trả về HTTP 410. Phát lại một sự kiện không kéo dài tính khả dụng của phương tiện.

Xác thực callback và xác nhận ngay lập tức

Mỗi lần POST mang theo:

X-APIMaster-Event-ID: evt_example
X-APIMaster-Delivery-ID: dlv_example
X-APIMaster-Timestamp: 1791014400
X-APIMaster-Signature: v1=<hex-hmac>,kid=<key-id>

Xác minh HMAC-SHA256 trên dấu thời gian, một dấu chấm theo nghĩa đen và các byte thô của phần thân yêu cầu bằng cách sử dụng khóa bí mật ký của endpoint. Sử dụng phép so sánh thời gian không đổi, cho phép sai lệch đồng hồ tối đa năm phút và kiểm tra xem tiêu đề Event-ID có khớp với ID trong phần thân không. Các lần thử lại giữ nguyên ID sự kiện và phần thân nhưng nhận một ID phân phối, dấu thời gian và chữ ký mới.

Trình nhận Python sau đây sử dụng Flask và SQLite. Nó lưu trữ một sự kiện một cách nguyên tử trước khi xác nhận nó. Worker ứng dụng của bạn nên tiêu thụ các hàng đã lưu, tải xuống tệp và chạy logic nghiệp vụ một cách riêng biệt.

import hashlib, hmac, json, os, sqlite3, time
from flask import Flask, request, jsonify, abort

app = Flask(__name__)
# During key rotation, configure both active and previous kid/secret pairs.
SECRETS = json.loads(os.environ["APIMASTER_WEBHOOK_SECRETS_JSON"])
DB_PATH = os.environ.get("WEBHOOK_DB_PATH", "webhook-events.sqlite3")
with sqlite3.connect(DB_PATH) as db:
    db.execute("CREATE TABLE IF NOT EXISTS events (id TEXT PRIMARY KEY, body BLOB NOT NULL)")

@app.post("/webhooks/apimaster")
def receive():
    raw = request.get_data()
    try:
        timestamp = request.headers["X-APIMaster-Timestamp"]
        if abs(time.time() - int(timestamp)) > 300:
            abort(401)
        fields = dict(part.split("=", 1) for part in
                      request.headers["X-APIMaster-Signature"].split(","))
        secret = SECRETS[fields["kid"]]
        expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw,
                            hashlib.sha256).hexdigest()
        if not hmac.compare_digest(expected, fields["v1"]):
            abort(401)
        event = json.loads(raw)
        if event["id"] != request.headers["X-APIMaster-Event-ID"]:
            abort(401)
    except (KeyError, ValueError, TypeError):
        abort(401)
    if event["type"] == "webhook.endpoint_verification":
        return jsonify(challenge=event["data"]["challenge"])
    with sqlite3.connect(DB_PATH) as db:
        db.execute("INSERT OR IGNORE INTO events(id, body) VALUES (?, ?)",
                   (event["id"], raw))
    return "", 204

Trả về bất kỳ trạng thái 2xx nào trong vòng 10 giây cho các sự kiện tạo. Xác nhận sau khi lưu trữ bền vững, mà không cần chờ tải xuống phương tiện. Việc phân phối là ít nhất một lần: các sự kiện trùng lặp là có thể, đặc biệt nếu một lần xác nhận bị mất, vì vậy hãy loại bỏ trùng lặp bằng id. Không có đảm bảo về thứ tự giữa các tác vụ.

Thử lại, lịch sử phân phối và phát lại

APIMaster thử lại các lỗi mạng, thời gian chờ xác nhận và phản hồi không phải 2xx trong tối đa 72 giờ kể từ khi tạo sự kiện. Các độ trễ ban đầu là 1, 2, 5, 15 và 30 phút, sau đó là 1, 2, 4 và 8 giờ, tiếp theo là các khoảng 12 giờ, với độ lệch tối đa 20%. Tiêu đề Retry-After hợp lệ trên mã 429/503 được tôn trọng trong cửa sổ thử lại. Các chuyển hướng không được theo dõi. HTTP 410 tạm dừng endpoint; các phản hồi 4xx khác được thử lại để cho phép sửa cấu hình.

curl --fail-with-body "https://apimaster.ai/v1/webhook-events?task_id=task_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl --fail-with-body "https://apimaster.ai/v1/webhook-events/evt_example/deliveries" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl --fail-with-body -X POST "https://apimaster.ai/v1/webhook-events/evt_example/redeliver" \
  -H "Authorization: Bearer YOUR_API_KEY"

Các trạng thái bao gồm pending, in_flight, retrying, delivered, paused và exhausted. Bản ghi sự kiện và lần thử được lưu giữ trong 30 ngày. Việc phát lại giữ nguyên ID sự kiện và tải trọng ban đầu và mở một cửa sổ phân phối mới 72 giờ; nó không tạo lại phương tiện hoặc tính phí lại. Cho phép tối đa năm lần phát lại thủ công cho mỗi sự kiện mỗi ngày UTC. Một sự kiện hiện đang được cho thuê để phân phối không thể được phát lại cho đến khi lần thử đó kết thúc hoặc hợp đồng thuê của nó hết hạn.

Tạm dừng hoặc tiếp tục một endpoint với PATCH /v1/webhook-endpoints/{id} và {"enabled":false} hoặc {"enabled":true}. Tiếp tục sẽ tiếp tục các sự kiện đã tạm dừng mà thời hạn ban đầu của chúng chưa qua. Xoay vòng khóa bí mật với POST /v1/webhook-endpoints/{id}/rotate-secret; lưu khóa bí mật và kid mới, và giữ lại cặp trước đó trong khoảng thời gian chuyển tiếp 24 giờ được trả về.

Dự phòng bằng Polling

Đối với các tác vụ không nhận được sự kiện kết thúc, hãy truy vấn /v1/videos/{task_id} hoặc truy vấn tác vụ hình ảnh được mô hình tài liệu hóa mỗi 60–120 giây. Sử dụng API tác vụ làm nguồn sự thật và kiểm tra lịch sử phân phối nếu việc tạo đã hoàn thành nhưng thông báo bị thiếu. Việc thiếu webhook không phải là lý do để gửi lại một yêu cầu tạo có tính phí. Thời gian ngừng hoạt động kéo dài của endpoint có thể làm cạn kiệt các lần thử lại tự động; khôi phục trình nhận và phát lại các sự kiện đã lưu giữ.