Medya kılavuzları

Seedance'i Volcengine'den Taşıma

Volcengine istek formatınızı koruyun ve Seedance'i TokenLab'e geçirin

Uygulamanız halihazırda Volcengine Seedance API'sini kullanıyorsa, REST yollarını, content[] gövdesini, yanıt alanlarını, geri çağrıları (callbacks) ve PascalCase materyal Action'larını koruyabilirsiniz. API ana bilgisayarını (host) değiştirin ve AK/SK imzalama yöntemini bir TokenLab API anahtarı ile değiştirin.

Neler Değişiyor

DeğişiklikMevcut Volcengine istemcisiTokenLab
Temel URLVolcengine uç noktanızhttps://api.tokenlab.sh/
Kimlik DoğrulamaAK/SK istek imzalamaAuthorization: Bearer <TOKENLAB_API_KEY>
Görev aktarımıResmi /api/v3/contents/generations/tasks REST yollarıKorundu
Materyal/doğrulama Action'larıAction ve Version sorgu parametreleriKorundu
Görev gövdesiVolcengine tarzı content[]Korundu
Materyal gövdesiGroupId ve ProjectName gibi PascalCase alanlarKorundu
Asenkron sonuçVolcengine görev yaşam döngüsüYoklama (polling) ve isteğe bağlı geri çağrı ile TokenLab cgt-... görev kimliği

Yalnızca AK/SK ile imzalanan istekler 401 AuthenticationError döndürür. Her TokenLab isteği Authorization: Bearer <TOKENLAB_API_KEY> içermelidir.

Bir uç nokta seçin

Mevcut istemciTokenLab uç noktası
Volcengine REST görev istemcisi/api/v3/contents/generations/tasks ve görev yolları
Materyal veya doğrulama Action istemcisiPOST /?Action=...&Version=2024-01-01 veya POST /api/v3?Action=...&Version=2024-01-01

Video görevleri için mevcut REST yöntemini, yolunu ve JSON gövdesini koruyun. Materyal ve doğrulama istekleri, Action ve Version sorgu parametrelerini kullanmaya devam eder. Action uç noktası ayrıca CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks ve DeleteContentsGenerationsTasks görev Action'larını da kabul eder; yeni çalışmalar için REST yollarını kullanın.

Resmi Görev Yolları

Yöntem ve yolAmaç
POST /api/v3/contents/generations/tasksBir video görevi oluşturun
GET /api/v3/contents/generations/tasks/{id}Bir görevi okuyun
GET /api/v3/contents/generations/tasksGörevleri listeleyin
DELETE /api/v3/contents/generations/tasks/{id}Kuyruktaki bir görevi iptal edin. Başlamış bir görev 409 task_not_cancellable döndürür

REST istemcileri şu eşdeğer referansları kullanabilir:

İstek Gövdesi Kuralları

  • content[]; text, image_url, video_url, audio_url ve draft_task öğelerini kabul eder.
  • image_url için role kısmını boş bırakın veya görüntüden videoya (image-to-video) dönüştürme için first_frame kullanın. İlk kare ile birlikte last_frame veya referanstan videoya (reference-to-video) dönüştürme için reference_image kullanın.
  • Seçilen Seedance iş akışının ilgili medya rolünü kabul ettiği durumlarda asset://asset-YYYYMMDDHHMMSS-xxxxx gibi genel bir materyal URI'si kullanılabilir.
  • REST gövdesi; model, content, ratio, duration, resolution, generate_audio, watermark, return_last_frame, seed, execution_expires_after ve safety_identifier dahil olmak üzere yalnızca resmi alanları kabul eder. Varsayılanlar modele bağlıdır: generate_audio, seedance-2.0 modelleri için false, seedance-2.5 için true değerindedir; duration ise seedance-2.0 modelleri için 5, seedance-2.5 için -1 değerindedir. Bu REST formatı 480p, 720p ve 1080p (seedance-2.5 için 480p ve 720p) çözünürlük değerlerini kabul eder, ancak yalnızca birleşik /v1/videos/generations API'sinin kabul ettiği 4k değerini kabul etmez. seedance-2.5, seed, frames ve camera_fixed parametrelerini reddeder.
  • callback_url, genel bir HTTP(S) uç noktasını kabul eder. TokenLab; queued, running, succeeded, failed ve expired durumları için aynı sorgu-görev gövdesini gönderir; yalnızca succeeded ve failed resmi davranışı izler: beş saniyelik bir zaman aşımı ve uç noktanız bildirimi onaylamadığında yeniden deneme.

Minimal REST Örneği

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.5",
    "content": [
      {"type":"text","text":"A cinematic product reveal"},
      {"type":"image_url","role":"reference_image","image_url":{"url":"https://example.com/reference.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'

Döndürülen cgt-... kimliğini saklayın. status değeri succeeded, failed, cancelled veya expired olana kadar yoklama yapın; oluşturma yanıtını tamamlanmış bir video olarak değerlendirmeyin. callback_url sağlarsanız, tekrarlanan succeeded veya failed bildirimlerine izin verin ve kurtarma yolu olarak yoklamaya devam edin.

v1 ve v3 Türlerini Ayrı Tutun

Bu uç nokta için /v1/tasks/{id} yanıt yapısını yeniden kullanmayın. Birleşik v1 API; pending, processing, completed ve failed durumlarını bildirirken, Volc uyumlu v3 API; queued, running, succeeded, failed, cancelled ve expired durumlarını bildirir. Resmi v3 yanıtı ayrıca duration değerini bir JSON dizgesi olarak temsil eder ve başarısız olmayan görevlerde error alanını atlar.

Oluşturma zaman aşımı veya bağlantı kesilmesinden sonra güvenli kurtarma için, REST oluşturma isteğine benzersiz bir Idempotency-Key ekleyin. Aynı gövdeyi aynı anahtarla yeniden denemek orijinal cgt-... kimliğini döndürür; farklı bir gövde ile aynı anahtar 409 döndürür.

Materyaller ve Gerçek Kişi Doğrulaması

Aynı Action uç noktası, 10 materyal ve materyal grubu işlemini de destekler. Tam PascalCase gövdeleri, filtreler, sayfalama, yanıt zarfı ve 12 saatlik materyal URL'leri için Materyal Action'ları (Volc Uyumlu) bölümüne bakın.

Gerçek kişi materyalleri, yüklemeden önce iki Action ekler:

  1. Görsel Doğrulama Oturumu Oluştur
  2. Görsel Doğrulama Sonucunu Al

İkinci Action, doğrulanmış GroupId değerini döndürür. Bu kimliği CreateAsset ile kullanın; bir istemci doğrudan bir LivenessFace grubu oluşturamaz.

Taşıma Kontrol Listesi

  1. API ana bilgisayarını https://api.tokenlab.sh ile değiştirin.
  2. AK/SK imzalama yöntemini bir TokenLab Bearer API anahtarı ile değiştirin.
  3. Resmi REST görev yöntemini, yolunu ve istek gövdesi büyük/küçük harf kullanımını koruyun; Action ve sürümü yalnızca materyal veya doğrulama işlemleri için tutun.
  4. İlgili materyal ve doğrulama isteklerinde aynı ProjectName değerini koruyun.
  5. Bu uç noktalar tarafından döndürülen TokenLab görev, grup ve varlık (asset) kimliklerini saklayın.
  6. Üretim trafiğini taşımadan önce bir oluşturma, yoklama, listeleme ve hata yanıtını doğrulayın.

Bu sayfada