Video ve materyaller
Görev Oluştur (Volc Uyumlu)
Volc uyumlu API ile bir Seedance görevi oluşturun.
Genel Bakış
Mevcut Volc tarzı Seedance istemcileri, API adresini ve anahtarını değiştirerek TokenLab'i kullanabilirler.
Örnekler Seedance 2.0 kullanmaktadır. Bu uç nokta, aşağıdaki modele özgü farklılıklarla Seedance 2.5'i de destekler. Bu sayfadaki yeniden kullanılabilir TokenLab materyal URI örnekleri Seedance 2.0 için geçerlidir.
Ayrıca bkz. Seedance 2.0 Video Modelleri ve Video Oluşturma.
Kimlik Doğrulama ve Uç Noktalar
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ı
type: "text", istem metnidir.roleiçermeyen veyarole: "first_frame"içerentype: "image_url", ilk kare olarak kabul edilir.role: "last_frame", bir ilk kare ile eşleştirilmelidir.type: "video_url",role: "reference_video"gerektirir vetype: "audio_url",role: "reference_audio"gerektirir.role: "reference_image", bir referans görselini işaret eder.- Öğe sınırları: Seedance 2.0, 16 adede kadar
contentöğesini (1 metin, 9 görsel, 3 video, 3 ses, 1draft_task) kabul eder. Seedance 2.5, 51 adede kadar (1 metin, 30 görsel, 10 video, 10 ses, 1draft_task) kabul eder. image_url.url, genel bir görsel URL'sini veyaasset://asset-YYYYMMDDHHMMSS-xxxxxgibi bir materyal URI'sini kabul eder.role, bu materyalin ilk kare, son kare veya referans görseli olup olmadığını belirler.- İlk/son kare girişlerini referans medyasıyla tek bir istekte karıştırmayın.
- REST gövdesi yalnızca bu sayfadaki alanları kabul eder.
material_asset_idvematerial_asset_idsdahil olmak üzere diğer tüm üst düzey alanlar400 UnsupportedParameterhatası döndürür.image_url.urliçine bir TokenLab materyal URI'si yerleştirin.
Parametre Notları
model, seedance-2.0 veya seedance-2.5 gibi bir TokenLab model kimliğini kabul eder. Mevcut istemciler, bu modeller için halihazırda kullandıkları Volcengine model kimliğini göndermeye devam edebilirler. Görev alma yanıtı, gönderdiğiniz model değerini döndürür. Tanınmayan bir değer 400 InvalidParameter hatası döndürür.
duration, saniye cinsinden bir tam sayıdır; -1 otomatik süreyi seçer. Varsayılanlar ve sınırlar modele göre farklılık gösterir:
| Parametre | Seedance 2.0 | Seedance 2.5 |
|---|---|---|
duration | 4–15 / -1 (varsayılan: 5) | 4–30 / -1 (varsayılan: -1) |
resolution | 480p, 720p, 1080p (varsayılan: 720p) | 480p, 720p (varsayılan: 720p) |
generate_audio | boolean (varsayılan: false) | boolean (varsayılan: true) |
priority | Desteklenmiyor | integer: 0–9 |
seed | integer: -1–4294967295 (varsayılan: -1) | Desteklenmiyor |
execution_expires_after | 3600–259200 saniye (varsayılan: 172800) | 3600–259200 saniye (varsayılan: 172800) |
Seedance 2.5 için ilk kare, ilk/son kare, video uzatma ve video-video istekleri ratio: "adaptive" gerektirir; video-video ayrıca duration: -1 gerektirir. output_format, yalnızca Seedance 2.5 için mp4 veya mov kabul eder.
ratio,16:9,4:3,1:1,3:4,9:16,21:9veyaadaptive(varsayılan:adaptive) kabul eder.watermarkvereturn_last_frameboolean değerlerdir (varsayılan:false).safety_identifier, 64 karaktere kadar bir dizidir.service_tieryalnızcadefaultkabul eder;flexdeğeri400 UnsupportedParameterdöndürür.tools, en fazla bir öğe kabul eder:{"type": "web_search"}.draft: true,framesvecamera_fixeddesteklenmez.camera_fixed: false, yalnızca Seedance 2.0 için kabul edilir.callback_url, 2.048 karaktere kadar genel bir HTTP(S) uç noktasına işaret edebilir.
Geri Arama (Callback) Teslimatı
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, görev alma 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 (task ID) kaydedin. Bir geri arama teslim edilmezse, sonucu yine de görev alma uç noktasıyla alabilirsiniz.
Görsel Hazırlığı
Genel HTTP(S) görsel URL'leri ve desteklenen veri URL'leri sağlandığı gibi kullanılır; bunlar otomatik olarak yeniden kullanılabilir materyaller olarak kaydedilmez. Açık asset://asset-... referansları, mevcut TokenLab materyallerini kullanır. TokenLab, oluşturma işleminden önce sahipliği ve hazır olma durumunu kontrol eder. Referans verilen bir materyal hala hazırlanıyorsa, hazır olana kadar bekleyin ve tekrar deneyin; oluşturma başarısız olduğunda error.code ve error.message değerlerini 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ı
{
"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 Önleme
Oluşturma istekleriyle birlikte benzersiz bir Idempotency-Key (1–255 karakter, satır sonu içermez) gönderin. Yanıt gelmeden bağlantı kapanırsa, aynı API anahtarı, idempotency anahtarı ve istek gövdesi ile tekrar deneyin:
- Orijinal görev oluşturulduysa, TokenLab aynı
cgt-...kimliğini döndürür veIdempotency-Replayed: truebaşlığını ekler. - Anahtarı farklı bir gövde ile yeniden kullanmak,
idempotency_conflictkoduyla409hatası döndürür ve asla ikinci bir görev oluşturmaz. - 255 karakterden uzun veya satır sonu içeren bir anahtar
400 InvalidParameterhatası döndürür.
Anahtar, JSON yanıt şeklini değiştirmez. TokenLab, X-Request-ID üzerinden veya anahtar olmadan aynı istek gövdelerinden yinelenenleri çıkarmaz.
Örnek
REST ile Oluşturma
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": "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"}
}
]Hatalar
REST hataları {"error": {"code", "message", "param", "type"}} yapısını kullanır. İstek sorunları InvalidParameter veya UnsupportedParameter ile 400 hatası döndürür ve eksik Bearer anahtarı 401 AuthenticationError döndürür. Yetersiz bakiye (402) veya hız sınırı (429) gibi video oluşturmadan kaynaklanan hatalar, kendi HTTP durum kodlarını korur.
Aynı işlemler, POST /api/v3?Version=2024-01-01 üzerinde CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks ve DeleteContentsGenerationsTasks Eylemleri olarak da mevcuttur. Yeni entegrasyonlar yukarıdaki REST yollarını kullanmalıdır.
Sonraki Adım
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": "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 }'{ "id": "string"}Yetkilendirme
BearerAuth API Anahtarı kimlik doğrulaması. API anahtarlarını Dashboard > API > API Keys bölümünden oluşturun veya yönetin.
Konum: header
Başlıklar
İstek bazlı Teslimat politikası. API anahtarı ve Çalışma Alanı varsayılanlarını geçersiz kılar. Otomatik olarak önce TokenLab Verified dener ve çıktı, istek kabulü veya kalıcı kaynak oluşturma öncesinde bir kez Official seçeneğine geçiş yapabilir.
Geçerli değerler
- "auto"
- "verified"
- "official"
İstemci tarafından oluşturulan, satır sonu içermeyen 1-255 karakterlik, eşdeğer (idempotent) REST görevi oluşturma anahtarı. Aynı TokenLab API kimlik bilgisi altında, aynı JSON gövdesiyle aynı anahtarın yeniden kullanılması orijinal cgt görev kimliğini döndürür; farklı bir gövdeyle yeniden kullanılması 409 koduyla idempotency_conflict hatası döndürür. Çok uzun veya satır sonu içeren bir anahtar 400 hatası döndürür. Zaman aşımı veya bağlantı kesilmesinden sonra yeniden denerken kimlik bilgisini, anahtarı ve istek gövdesini değiştirmeyin.
1 <= length <= 255İstek gövdesi
application/json
Yanıt
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json