APIMaster asenkron görev webhook'ları

Webhook'ları asenkron üretim için birincil bildirim mekanizması olarak kullanın ve yoklamayı yedek olarak tutun. APIMaster, izlenen bir görev tamamlandığında veya başarısız olduğunda imzalı bir HTTPS POST gönderir. Bildirimler, üretim sağlayıcısından bağımsızdır ve APIMaster görev kimliğinizi kullanır.

Desteklenen modeller ve uç noktalar

Seedance dört modeli de içerir: seedance-2.0, seedance-2.5, seedance-2.0-fast ve seedance-2.0-mini. POST /v1/videos/generations veya uyumlu POST /v1/video/generations kullanın.

Video görev bildirimleri ayrıca MiniMax-H3, Kling Omni / Motion Control, Grok Imagine Video ve Sora'yı da destekler. Desteklenen GPT Image 2 / 2.5 ve Gemini görsel iş akışları /v1/images/generations/async veya desteklenen /v1/images/edits/async kullanır; Midjourney v8.2 / Niji 7, /v1/midjourney/generations kullanır. Rota kullanılabilirliği ve üretim parametreleri yine de her modelin kılavuzunu takip eder. Senkron Seedream ve Grok görsel üretimi, sohbet akışı ve Seedance varlık incelemesi bu üretim webhook sözleşmesinin parçası değildir.

Model uygunluğu için GET /v1/webhook-capabilities?model=seedance-2.0-fast kontrol edin. Desteklenen bir asenkron gönderim uç noktası kullanın; uygunluk, her görsel işlemin veya her model takma adının asenkron üretimi desteklediği anlamına gelmez.

Bir uç nokta kaydedin ve doğrulayın

API anahtarınızı Authorization: Bearer YOUR_API_KEY içinde kullanın. Bir API anahtarı, kendi hesabına ait uç noktaları ve olayları yönetebilir. Sunucunuzda saklayı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"}'

Yanıt endpoint.id, endpoint.key_id ve signing_secret içerir. İmzalama sırrını güvenli bir şekilde saklayın: sadece bir kez döndürülür. API anahtarınızdan ayrıdır ve üretimi veya indirmeleri yetkilendiremez. URL, 443 numaralı portta halka açık erişilebilir bir HTTPS uç noktası olmalıdır. Özel adresler ve yönlendirmeler reddedilir. Hesap başına en fazla 20 uç noktaya izin verilir; URL'ler değiştirilemez, bu nedenle hedefi değiştirirken yeni bir uç nokta oluşturun ve doğrulayın.

Alıcınızı yapılandırdıktan sonra, sahipliği doğrulayın:

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

APIMaster, data.challenge içeren imzalı bir webhook.endpoint_verification olayı gönderir. 10 saniye içinde {"challenge":"THE_RECEIVED_CHALLENGE"} ile HTTP 200 döndürün. Doğrulanmamış, duraklatılmış veya başka bir hesaba ait bir uç noktaya atıfta bulunan bir üretim isteği, gönderimden önce reddedilir.

HTTP isteğinin toplam zaman aşımı DNS, bağlantı ve TLS dahil 10 saniyedir. Yanıt başlıkları istek gönderildikten sonra 8 saniye içinde gelmelidir. Olayı kalıcı olarak kaydedip hemen alındı yanıtı verin.

Bildirimlerle bir görev gönderin

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"
  }'

Model kimliğini, kendi desteklenen parametrelerini korurken dört Seedance kimliğinden herhangi biriyle değiştirin. Normal oluşturma yanıtından görev kimliğini kaydedin. client_reference_id en fazla 128 bayt olan isteğe bağlı bir iş referansıdır; bir gönderim idempotency anahtarı değildir. notifications ile eski webhook veya callback_url sağlayıcı parametrelerini birleştirmeyin.

Desteklenen çok parçalı görsel düzenlemeleri için, notifications bir JSON string form alanı olarak ve client_reference_id ayrı bir form alanı olarak gönderin:

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"

Bu sürümde hesap genelinde varsayılan bir uç nokta yoktur: her görev isteğinde bir uç noktaya başvurun. Webhook'lar gönderim yanıtınızdan önce gelebilir. Uygulamanız henüz döndürülen görev kimliğini kaydetmemiş olsa bile onları kalıcı hale getirin. Bazı görsel asenkron iş akışları senkron yukarı akış üretimini sarar, bu nedenle gönderimin kendisi hala zaman alabilir.

Başarı ve başarısızlık yükleri

Bir başarı bildirimi, genel görev kimliğini ve kimliği doğrulanmış bir video bağlantısını içerir:

{
  "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
  }
}

Başarısızlık, type: "task.failed", data.status: "failed", data.result: null ve bir hata nesnesi ile aynı zarfı kullanır:

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

Hem sağlayıcı tarafından onaylanan başarısızlıklar hem de ağ geçidi görev zaman aşımları başarısızlık olayları oluşturabilir. Bir görev kabul edilmeden önce reddedilen bir oluşturma isteği, bir görev olayı oluşturmaz. Bildirim teslim başarısızlığı, üretim durumunu değiştirmez veya üretimi yeniden çalıştırmaz. Olaylar, faturalama mutabakatının tamamlandığını onaylamaz.

Görseller için, kind image'dır ve outputs tüm mevcut görsel çıktıları içerir. Midjourney alt görev olayları batch_id içerir; ayrıca tüm alt görevler tamamlandıktan sonra bir toplu özet almak için batch.completed'a abone olabilirsiniz. Durumu completed, partial_failure veya failed'dir ve sayılar data.summary içindedir. Toplu tamamlama her zaman her alt görevin başarılı olduğu anlamına gelmez.

Çıktı URL'lerini, görevin hesabına ait bir API anahtarıyla indirin. Üretilen medyayı derhal kaydedin. expires_at: null, kalıcı depolama değil, garanti edilen bir sona erme süresi sağlanmadığı anlamına gelir; daha sonraki bir indirme HTTP 410 döndürebilir. Bir olayın yeniden oynatılması medya kullanılabilirliğini uzatmaz.

Geri aramaları doğrulayın ve zamanında onaylayın

Her POST şunları taşır:

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>

Zaman damgası, gerçek bir nokta ve ham istek gövdesi baytları üzerinde HMAC-SHA256'yı, uç noktanın imzalama sırrı kullanılarak doğrulayın. Sabit zamanlı karşılaştırma kullanın, en fazla beş dakikalık saat sapmasına izin verin ve Event-ID başlığının gövde ID'si ile eşleştiğini kontrol edin. Yeniden denemeler aynı olay ID'sini ve gövdeyi korur ancak yeni bir teslimat ID'si, zaman damgası ve imza alır.

Aşağıdaki Python alıcısı Flask ve SQLite kullanır. Bir olayı onaylamadan önce atomik olarak kalıcı hale getirir. Uygulama işçiniz kaydedilen satırları tüketmeli, dosyaları indirmeli ve iş mantığını ayrı olarak çalıştırmalıdır.

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

Üretim olayları için herhangi bir 2xx durumunu 10 saniye içinde döndürün. Kalıcı depolamadan sonra, medya indirmelerini beklemeden onaylayın. Teslimat en az bir kezdir: yinelenen olaylar mümkündür, özellikle bir onay kaybolduğunda, bu nedenle id ile yinelemeleri kaldırın. Görevler arasında sıralama garantisi yoktur.

Yeniden denemeler, teslimat geçmişi ve yeniden oynatma

APIMaster, ağ hataları, onay zaman aşımları ve 2xx olmayan yanıtlar için olay oluşturulmasından itibaren 72 saat boyunca yeniden dener. İlk gecikmeler 1, 2, 5, 15 ve 30 dakika, ardından 1, 2, 4 ve 8 saat, sonrasında 12 saatlik aralıklardır ve %20'ye kadar jitter uygulanır. 429/503 üzerindeki geçerli Retry-After yeniden deneme penceresi içinde dikkate alınır. Yönlendirmeler takip edilmez. HTTP 410 uç noktayı duraklatır; diğer 4xx yanıtları yapılandırma düzeltmelerine izin vermek için yeniden denenir.

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"

Durumlar pending, in_flight, retrying, delivered, paused ve exhausted içerir. Olay ve deneme kayıtları 30 gün boyunca saklanır. Yeniden oynatma, orijinal olay ID'sini ve yükünü korur ve yeni bir 72 saatlik teslimat penceresi açar; medyayı yeniden oluşturmaz veya tekrar ücretlendirmez. Olay başına UTC günü başına en fazla beş manuel yeniden oynatmaya izin verilir. Teslimat için şu anda kiralanmış bir olay, o deneme sona erene veya kira süresi dolana kadar yeniden oynatılamaz.

Bir uç noktayı PATCH /v1/webhook-endpoints/{id} ve {"enabled":false} veya {"enabled":true} ile duraklatın veya devam ettirin. Devam ettirme, orijinal son teslim tarihi geçmemiş duraklatılmış olayları sürdürür. Sırları POST /v1/webhook-endpoints/{id}/rotate-secret ile döndürün; yeni sırrı ve kid'i kaydedin ve önceki çifti döndürülen 24 saatlik geçiş süresi boyunca saklayın.

Yedekleme için sorgulama

Alınmış bir terminal olayı olmayan görevler için, her 60–120 saniyede bir /v1/videos/{task_id} veya modelin belgelenmiş görüntü-görev sorgusunu sorgulayın. Görev API'sini gerçek kaynak olarak kullanın ve üretim tamamlandıysa ancak bildirim eksikse teslimat geçmişini kontrol edin. Eksik bir webhook, faturalanabilir bir üretim isteğini yeniden göndermek için bir neden değildir. Kalıcı uç nokta kesintisi otomatik yeniden denemeleri tüketebilir; alıcıyı geri yükleyin ve saklanan olayları yeniden oynatın.