Görev Oluştur (Volc Uyumlu)

Genel BakışCopy Anchor Link

Mevcut Volc tarzı Seedance istemcileri, API adresini ve anahtarını değiştirerek TokenLab'i kullanabilirler.

Ayrıca bkz: Seedance 2.0 Video Modelleri ve Video Oluşturma.

Kimlik Doğrulama ve Uç NoktalarCopy Anchor Link

• Authorization: Bearer <TOKENLAB_API_KEY> kullanın.
• Volc AK/SK imzası kabul edilmez. İstekler bir TokenLab Bearer anahtarı içermelidir.
• Resmi görev yolunu kullanın: POST /api/v3/contents/generations/tasks.

İçerik KurallarıCopy Anchor Link

• type: "text" istem metnidir.
• role içermeyen veya role: "first_frame" içeren type: "image_url", ilk kare olarak kabul edilir.
• role: "last_frame", bir ilk kare ile eşleştirilmelidir.
• role: "reference_image", reference_video ve reference_audio referans olarak kullanılır.
• image_url.url, genel bir resim URL'sini veya asset://asset-YYYYMMDDHHMMSS-xxxxx gibi bir materyal URI'sini kabul eder. role, bu materyalin ilk kare, son kare veya referans resmi olup olmadığını belirler.
• İlk/son kare girişlerini referans medyasıyla tek bir istekte karıştırmayın.
• Üst düzey material_asset_id ve material_asset_ids alanları reddedilir. TokenLab materyal URI’sini image_url.url içine koyun. priority yalnızca Seedance 2.5 için desteklenir.

Parametre NotlarıCopy Anchor Link

duration saniye cinsinden bir tam sayıdır; -1 otomatik süreyi seçer. Varsayılanlar ve sınırlar modele göre değişir:

Seedance 2.5 için ilk kare, ilk/son kare, video uzatma ve videodan videoya istekler ratio: "adaptive" gerektirir. Videodan videoya istekler ayrıca duration: -1 gerektirir. output_format, mp4 veya mov değerlerini yalnızca Seedance 2.5 için kabul eder.

• ratio, 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 veya adaptive değerlerini kabul eder.
• watermark, return_last_frame, seed, execution_expires_after ve safety_identifier, seçilen model için geçerli olduklarında kabul edilir.
• callback_url, genel bir HTTP(S) uç noktasına işaret edebilir.

Geri Arama (Callback) TeslimatıCopy Anchor Link

callback_url mevcut olduğunda, TokenLab görev durumu değiştiğinde bir HTTP POST gönderir. Geri arama durumları queued, running, succeeded, failed ve expired şeklindedir. JSON gövdesi, get-task yanıtıyla eşleşir.

2xx yanıtı, teslimatı onaylar. succeeded ve failed durumları için, beş saniye içinde başarılı olmayan bir teslimat, üç defaya kadar yeniden denenir. Geri arama yalnızca standart JSON içerik başlığına sahiptir ve TokenLab'e özgü teslimat başlıkları içermez. Yönlendirmeler takip edilmez ve özel veya ayrılmış ağ hedefleri reddedilir.

Görev kimliğini (ID) kaydedin. Geri arama teslim edilmezse, sonucu get-task uç noktası ile yine de alabilirsiniz.

Resim HazırlığıCopy Anchor Link

Herkese açık HTTP(S) görüntü URL’leri ve desteklenen data URL’leri verildiği gibi kullanılır; yeniden kullanılabilir materyal olarak otomatik kaydedilmez. Açık asset://asset-... referansları mevcut TokenLab materyallerini kullanır. Üretim öncesinde sahiplik ve hazır olma durumu denetlenir. Materyal hâlâ hazırlanıyorsa hazır olmasını bekleyip yeniden deneyin. Oluşturma başarısız olursa error.code ve error.message alanlarını inceleyin.

Mevcut materyaller için, başka bir sistem tarafından döndürülen orijinal bir varlık kimliği yerine genel asset-YYYYMMDDHHMMSS-xxxxx kimliğini kullanın. TokenLab, oluşturma işleminden önce materyal sahipliğini doğrular.

Oluşturma YanıtıCopy Anchor Link

{
  "id": "cgt-20260102030405-a1b2c"
}

Oluşturma yanıtı yalnızca görev kimliğini içerir. Durumu ve sonuçları istediğiniz zaman alabilmek için bunu kaydedin.

Yinelenen Görevleri ÖnlemeCopy Anchor Link

Oluşturma istekleriyle birlikte benzersiz bir Idempotency-Key gönderin. Yanıt gelmeden bağlantı kapanırsa, aynı API anahtarı, idempotency anahtarı ve istek gövdesi ile yeniden deneyin:

• Orijinal görev oluşturulduysa, TokenLab aynı cgt-... kimliğini döndürür ve Idempotency-Replayed: true başlığını ekler.
• İlk istek hâlâ kaydediliyorsa TokenLab 409 IdempotencyRequestInProgress döndürür. Aynı anahtar ve gövdeyle daha sonra yeniden deneyin.
• Anahtarı farklı bir gövde ile yeniden kullanmak 409 IdempotencyConflict döndürür ve asla ikinci bir görev oluşturmaz.

Idempotency, resmi v3 REST oluşturma yolu için geçerlidir. JSON yanıt şeklini değiştirmez ve X-Request-ID'den veya anahtar içermeyen özdeş istek gövdelerinden çıkarılmaz.

ÖrnekCopy Anchor Link

REST OluşturmaCopy Anchor Link

curl https://api.tokenlab.sh/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Idempotency-Key: $CLIENT_JOB_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "content": [
      {"type": "text", "text": "A cinematic forest at sunset"},
      {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generate_audio": false,
    "callback_url": "https://example.com/webhooks/seedance"
  }'

Mevcut materyaller için, her URI'yi resmi content[] öğesine yerleştirin ve rolünü belirtin:

[
  {
    "type": "image_url",
    "role": "first_frame",
    "image_url": {"url": "asset://asset-20260720123458-start"}
  },
  {
    "type": "image_url",
    "role": "last_frame",
    "image_url": {"url": "asset://asset-20260720123459-end01"}
  }
]

Sonraki AdımCopy Anchor Link

Görev terminal bir duruma ulaşana kadar döndürülen cgt-... kimliğini Görev Al (Volc Uyumlu) ile kullanın.

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "doubao-seedance-2-0-260128",    "content": [      {        "type": "text",        "text": "A cinematic forest at sunset"      },      {        "type": "image_url",        "role": "reference_image",        "image_url": {          "url": "https://example.com/ref.png"        }      }    ],    "ratio": "16:9",    "duration": 5,    "resolution": "720p",    "generate_audio": false  }'

{  "id": "string"}