Seedance 2.5 Video Oluşturma API'si
Seedance 2.5 parametreleri, referans medyası, ilk ve son kareler, düzenleme, asenkron sonuçlar, faturalandırma ve sorun giderme için detaylı APIMaster kılavuzu.
Seedance 2.5 Video Oluşturma
Özellik desteği: Göndermeden önce
GET /v1/seedance2/private-avatar/capabilities?model=seedance-2.5yanıtındakiconfigured,method,reason,generation_capabilitiesvegeneration_route_enabledalanlarını kontrol edin. Otomatik süre, MOV, son kare ve seed ile tekrarlanabilirlik hizmete bağlıdır. Desteklenmeyen seçenekler hata döndürür; sonuçlar gerçek dosya biçiminde sunulur.Active, kimlik doğrulamasını kanıtlamaz.
Kimlik doğrulama ve aynı kişiye ait materyaller. Kimlik doğrulama, materyal incelemesi ve sıradan veya sanal materyal yükleme ayrı süreçlerdir. Yalnızca açık kullanım izni olan fotoğrafları gönderin.
seedance-2.5 genel model kimliğini kullanarak metin, görsel, video veya ses referanslarından video oluşturun. Oluşturma asenkron işler: bir istek gönderin, genel görev kimliğini kaydedin, bitene kadar durumunu sorgulayın ve sonucu indirin. Başarılı bir gönderim, görevin kabul edildiği anlamına gelir; bir videonun zaten oluşturulduğu anlamına gelmez.
Kare, düzenleme ve genişletme görevleri için önemli: varsayılan en-boy oranı
adaptive'dir. Bu değeri koruyun veya oranı belirtmeyin;16:9gibi sabit bir oranı açıkça göndermeyin. Yalnızca ilk/son kare içeren bir görsel görevi için, çıktı ilk görselin oranlarını takip eder. Belirli bir oran gerekiyorsa, görselinizi önce kırpın veya dolgu ekleyin.
Varsayılan değişiklikler — 2026-10-01: belirtilmeyen
durationartık4yerine5saniye anlamına gelir; varsayılan oran16:9yerineadaptive'dir; oluşturulan ses varsayılan olaraktrueolur. Entegrasyonunuz sabit bir süre, oran veya sessiz çıktıya bağlıysa bu alanları açıkça belirleyin.
Süre sınırları (2026-10-06 tarihinde doğrulandı)
duration, çıktı videosunun saniye cinsinden uzunluğudur: 4 ile 30 arasında bir tam sayı. Normal üretim otomatik süre için duration: -1 destekler. Video düzenleme (omni_reference_task_type: "edit") için -1 zorunludur ve kaynak video 4–30 saniye olmalıdır.
En fazla 10 referans video; her biri 2–30 saniye ve toplam en fazla 30 saniye. Referans ses için aynı sayı ve süre sınırları geçerlidir. Girdi ve çıktı sınırları ayrıdır. Ücretlendirilen saniyeler ikisini kapsayabilir ancak çıktı sınırını artırmaz.
Göndermeden önce parametreleri kontrol edin. HTTP 200 ve task_id yalnızca kabulü doğrular; sonraki HTTP 400 / InvalidParameter görevi başarısız kılabilir. Hata mesajını okuyun, parametreleri düzeltin ve yeni görev oluşturun. Değişmemiş isteği tekrarlamayın. Başarısız görevlerin üretim rezervasyonu iade edilir.
Doğrulama kaynağı: Seedance API.
Kimlik Doğrulama ve Uç Noktalar
API temel URL'si https://apimaster.ai/v1'dir. APIMaster anahtarınızı API anahtarları sayfasından alın ve Authorization: Bearer YOUR_API_KEY başlığıyla gönderin. JSON istekleri ayrıca Content-Type: application/json başlığına ihtiyaç duyar. Anahtarlarınızı genel ön yüz kodunda değil, sunucunuzda saklayın.
| Metod | Uç Nokta | Amaç |
|---|---|---|
POST |
https://apimaster.ai/v1/videos/generations |
Önerilen JSON görev gönderimi |
GET |
https://apimaster.ai/v1/video/generations/{task_id} |
Uyumluluk formatında görev durumu |
GET |
https://apimaster.ai/v1/videos/{task_id} |
OpenAI tarzı video durumu |
GET |
https://apimaster.ai/v1/videos/{task_id}/content |
Kimlik doğrulamalı video indirme |
GET |
https://apimaster.ai/v1/videos/{task_id}/last-frame |
İstenmişse, kimlik doğrulamalı son kare indirme |
Bir video için durum sorgulamak üzere bir görsel-görev uç noktası kullanmayın. Görevi oluşturan hesaba ait bir anahtar kullanın.
Hızlı Başlangıç: Metinden Videoya
30 saniye veya daha yüksek çözünürlük talep etmeden önce, kısa bir klip ve açık bir belirtimle başlayın. Sonraki örneklerdeki örnek medya URL'lerini kendi doğrudan indirilebilir dosyalarınızla değiştirin.
curl --fail-with-body -sS "https://apimaster.ai/v1/videos/generations" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5",
"prompt": "A lighthouse above a calm sea at sunrise. Slow camera push-in, natural lighting, no text.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "adaptive",
"generate_audio": true,
"watermark": false,
"output_format": "mp4"
}'
Örnek gönderim yanıtı:
{
"code": 200,
"data": [{"status": "submitted", "task_id": "task_example"}],
"error": null
}
Döndürülen task_id değerini kaydedin ve görev durumunu ve nihai videoyu almak için sorgu uç noktasını kullanın.
İstek parametreleri ve varsayılanlar
| Alan | Tip | Varsayılan | Sözleşme |
|---|---|---|---|
model |
string | Yok; gerekli | seedance-2.5 |
prompt |
string | Yok; üretim için gerekli | Sahne, hareket, kamera ve referans niyeti; draft_task_id kullanırken atlayın |
duration |
integer | 5; edit içinde atlanırsa -1 olur |
4–30 saniye veya otomatik süre için -1; düzenleme yalnızca -1 kabul eder |
resolution |
string | 720p; önizleme 480p; önizleme yükseltme 1080p |
Normal üretim: 480p, 720p, 1080p; önizleme ve yükseltme yalnızca kendi çözünürlüklerini kabul eder |
aspect_ratio |
string | adaptive |
adaptive, 16:9, 4:3, 1:1, 3:4, 9:16, 21:9; kare/düzenle/uzat görevleri adaptive gerektirir |
ratio |
string | aspect_ratio ile aynı |
Takma ad; birlikte sağlanırsa her iki değer de eşleşmeli |
size |
string | Atlanırsa adaptive |
Eski boyut/oran kolaylık alanı; adaptive kabul edilir. resolution ve aspect_ratio tercih edilir |
image_urls |
string[] | Referans yok | Toplamda en fazla 30 görsel, image_with_roles dahil |
image_with_roles |
object[] | Referans yok | url ve role içeren nesneler; first_frame, last_frame veya reference_image |
image_urls, dizi sırasını koruyan reference_image girdileridir. Yalnızca referans görseller için image_with_roles gerekmez; başlangıç ve bitiş kareleri için first_frame / last_frame rollerini açıkça belirtin.
| first_frame_image / last_frame_image | string | Kare yok | İlgili görsel roller için takma adlar; HTTP(S) veya onaylanmış bir asset:// URL'si kullanın |
| video_urls | string[] | Referans yok | En fazla 10; toplam süre en fazla 30 saniye |
| audio_urls | string[] | Referans yok | En fazla 10; toplam süre en fazla 30 saniye; yalnızca ses referansları desteklenir |
| generate_audio | boolean | true | Ses üretilip üretilmeyeceği |
| audio | boolean | generate_audio ile aynı | Takma ad; çakışan ses değerleri 400 döndürür |
| watermark | boolean | false | Üretilmiş içerik filigranı istenip istenmeyeceği |
| seed | integer | Model tarafından seçilir | 0'ü açık bir tohum olarak koru; bir tohum aynı çıktıyı garanti etmez |
| output_format | string | mp4 | mp4 veya mov; MOV, düzenleme/uzatma iş akışları için kullanışlıdır. Kodlayıcı ve renk hassasiyeti sonuç dosyasına bağlıdır |
| omni_reference_task_type | string | auto | auto, reference, edit veya extend; aşağıdaki eşzamanlı doğrulamaya bakın |
| return_last_frame | boolean | false | Başarıdan sonra, kare hazır olduğunda last_frame_url döndür |
| draft | boolean | false | 480p önizleme üret; yalnızca seedance-2.5 |
| draft_task_id | string | Ayarlanmamış | Başarılı bir önizlemenin genel APIMaster kimliği; bunu yeni bir 1080p görevine yükseltir |
JSON boolean değerlerini kullanın, "false" gibi string değerleri kullanmayın. Çakışan takma adlar, desteklenmeyen çözünürlükler, geçersiz süre ve göreve özgü kısıtlamalar, bir görev oluşturulmadan veya rezervasyonu ücretlendirilmeden önce HTTP 400 döndürür. Atlanan isteğe bağlı diziler referans olmadığı anlamına gelir.
Ek alanlar ve girdi formları
| Alan veya girdi | Arayüz desteği |
|---|---|
negative_prompt |
Metin olarak kabul edilir |
first_frame_image / last_frame_image |
Desteklenen string takma adlar; aynı kareyi image_with_roles içinde yinelemeyin |
| Base64 / data-URL görseller | Üretim URL'si olarak desteklenmez. Dosyayı /v1/uploads/images üzerinden yükleyin ve döndürülen URL'yi kullanın |
generation_type |
Normal üretim için isteğe bağlı bir alan olarak kabul edilir; görev tipi sözleşmesi için omni_reference_task_type kullanın |
camerafixed |
Normal üretim için bir boolean olarak kabul edilir; gerekli kamera hareketini prompt'ta açıklayın |
service_tier |
Normal üretim için isteğe bağlı; hem önizlemeler hem de önizleme yükseltmeleri için reddedilir |
Belirli bir görsel sonuç veya planlama önceliği garanti etmek için generation_type, camerafixed veya service_tier'ye güvenmeyin. Bunlar, belgelenmiş görev tipi ve prompt gereksinimlerinin yerine geçmez.
Görev türünü seçin
| Görev | Girdi ve amaç | Gerekli ayarlar |
|---|---|---|
| Metinden videoya | Referans medya olmadan prompt | Desteklenen bir en-boy oranı, çözünürlük ve süre seçin |
| Referans oluşturma | Referans görseller/video/ses ve yeni bir sahnenin açıklaması | Sabit en-boy oranları mümkündür; prompt'un referans oluşturmayı açıkça tanımladığından emin olun |
| İlk kare oluşturma | Rolü first_frame olan bir görsel |
aspect_ratio: "adaptive" |
| İlk ve son kare oluşturma | Bir first_frame ve bir last_frame |
aspect_ratio: "adaptive"; bir son kare için ilk kare gereklidir |
| Video düzenleme | Kaynak video artı içeriği düzenlemeyi, kaldırmayı, değiştirmeyi veya değiştirmeyi isteyen bir prompt | aspect_ratio: "adaptive", duration: -1; kaynak video 4–30 saniye |
| Video uzatma | Kaynak video artı onu devam ettirmeyi veya uzatmayı isteyen bir prompt | aspect_ratio: "adaptive"; referans medyayı aşağıdaki limitler dahilinde tutun |
omni_reference_task_type açıkça auto, reference, edit veya extend seçebilir. Eşleşen bir prompt kullanın: reference beyan ederken bir nesneyi değiştirmeyi istemek yine de bir görev türü uyuşmazlığına yol açabilir. Düzenleme için, atlanan süre -1 olarak normalize edilir; atlanan en-boy oranı adaptive'dir. Açık değerler aynı kısıtlamaları karşılamalıdır. Referans oluşturma için, amaçlanan işlem bu değilse, düzenleme veya uzatma talimatlarından kaçının.
Senkron görev türü doğrulaması
| Beyan edilen tür | Kabulden önce doğrulama |
|---|---|
edit |
En az bir video_urls girişi; en-boy oranı atlanmış veya adaptive; süre atlanmış veya -1; kaynak video 4–30 saniye |
extend |
En az bir video_urls girişi; en-boy oranı atlanmış veya adaptive |
reference |
Sıradan desteklenen en-boy oranı ve süre limitleri uygulanır; düzenleme/uzatma kısıtlaması yok |
auto |
Görev amacı prompt ve referanslardan çıkarılır |
Açık seçim geçersiz parametreleri gönderimde yakalar: HTTP 400, görev yok, oluşturma rezervasyonu yok. Görev amacı ayrıca oluşturma sırasında değerlendirilir; beyan edilen türle tutarsız bir prompt asenkron olarak InvalidParameter.TaskTypeMismatch ile başarısız olabilir. edit için bir düzenleme prompt'u, extend için bir devam ettirme prompt'u ve reference için yeni bir sahne prompt'u yazın.
Görsel rolleri ve ilk/son kareler
image_with_roles girişleri {"url": "https://example.com/frame.png", "role": "first_frame"} kullanır. Roller first_frame, last_frame ve reference_image'dir. En fazla bir ilk kare ve bir son kare kullanın. Referans görseller görünüş veya kompozisyonu yönlendirir; kesin bir başlangıç karesi dayatmaz. Örtüşen image_urls ve image_with_roles tanımlarını karıştırmaktan kaçının.
Video veya ses referansları da dahil edilmişse, kare rolleri katı bir ilk/son kare görevi yerine genel referans görselleri olarak ele alınabilir. Kesin kare sabitleme gerektiğinde sadece görsel girdi kullanın.
{
"model": "seedance-2.5",
"prompt": "The camera moves smoothly from the first view to the last view. Preserve the building and lighting.",
"image_with_roles": [
{"url": "https://example.com/first.png", "role": "first_frame"},
{"url": "https://example.com/last.png", "role": "last_frame"}
],
"duration": 5,
"resolution": "720p",
"aspect_ratio": "adaptive",
"generate_audio": false
}
Tek bir başlangıç karesi için, last_frame girişini kaldırın. Farklı bir çıktı en-boy oranına ihtiyacınız varsa, ilk görseli göndermeden önce o orana kırpın veya doldurun; sadece aspect_ratio'u değiştirmek yeterli değildir.
Görsel, video ve ses referansları
Her referansa prompt'ta net bir amaç verin. Referanslar dizi sırasına göre 1'dan indekslenir; @图片1, @视频1 ve @音频1 gibi açıklamalar görsel, video ve ses referanslarını tanımlayabilir. İstekte bulunmayan bir indekse atıfta bulunmayın.
{
"model": "seedance-2.5",
"prompt": "Create a new coastal scene using @图片1 for the color palette, @视频1 for camera movement, and @音频1 for the rhythm. Do not edit or extend the original video.",
"image_urls": ["https://example.com/palette.png"],
"video_urls": ["https://example.com/camera-reference.mp4"],
"audio_urls": ["https://example.com/rhythm.mp3"],
"omni_reference_task_type": "reference",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": true
}
Sadece ses referanslı oluşturma için, audio_urls'u tutun ve görsel/video dizilerini kaldırın. Tüm medya, bir tarayıcı girişi, çerezler veya ek yetkilendirme başlıkları olmadan oluşturma servisi tarafından erişilebilir olmalıdır.
Bir videoyu düzenleyin
{
"model": "seedance-2.5",
"prompt": "Edit the video: replace the red umbrella with a blue umbrella while preserving the subject and camera motion.",
"video_urls": ["https://example.com/source.mp4"],
"omni_reference_task_type": "edit",
"duration": -1,
"resolution": "720p",
"aspect_ratio": "adaptive",
"generate_audio": true,
"output_format": "mov"
}
Düzenleme kaynak klibin süresini takip eder. Otomatik süre daha büyük bir başlangıç bakiyesi rezervasyonu gerektirebilir; aşağıdaki faturalandırmaya bakın.
Bir videoyu uzatın
{
"model": "seedance-2.5",
"prompt": "Extend the video forward: the cyclist continues along the same path, keeping the lighting and camera direction consistent.",
"video_urls": ["https://example.com/source.mp4"],
"omni_reference_task_type": "extend",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "adaptive",
"generate_audio": true
}
Referans medya gereksinimleri
Bunlar çıktı boyutları değil, girdi medya limitleridir. Başarıyla indirilen bir dosya, gerçek formatı, boyutları, süresi veya içeriği uygun olmadığı için reddedilebilir.
| Girdi | Adet | Boyutlar ve süre | Dosya gereksinimleri |
|---|---|---|---|
| Görseller | En fazla 30 referans görsel; kare modu bir veya iki görsel kullanır |
Her bir kenar 300–6000 piksel; genişlik/yükseklik oranı 0.4–2.5 |
Her dosya 30 MB altında. JPEG/PNG önerilir; diğer kabul edilen formatlar arasında WebP, BMP, TIFF, GIF, HEIC, HEIF bulunur (çözme desteğine tabidir) |
| Videolar | En fazla 10; toplam süre en fazla 30 saniye |
Her klip 2–30 saniye; düzenleme kaynağı 4–30 saniye. Her bir kenar 300–6000 piksel; oran 0.4–2.5; piksel sayısı 409600–8295044; 24–60 FPS |
Her dosya en fazla 200 MB; H.264 veya H.265 video ve AAC veya MP3 ses içeren MP4/MOV; desteklenen çözünürlük seviyeleri 480p, 720p, 1080p |
| Ses | En fazla 10; toplam süre en fazla 30 saniye |
Her klip 2–30 saniye |
Her dosya en fazla 15 MB; WAV veya MP3 |
Bir paylaşım sayfasının HTML URL'si yerine doğrudan HTTPS dosya URL'lerini kullanın. .png dosya adı, bir HTML hata sayfasını geçerli bir görsel yapmaz. Geçici imzalı URL'lerin, görevin medyayı alması için yeterince uzun süre geçerli kalmasını sağlayın. Giriş sayfalarına yönlendirmelerden ve IP veya sıcak bağlantı koruma kurallarıyla kısıtlanmış bağlantılardan kaçının. Maksimum görsel uyumluluğu için dosyayı RGB JPEG veya PNG'ye dönüştürün ve gerçek genişliğini ve yüksekliğini doğrulayın.
Yalnızca kullanma yetkiniz olan medyayı yükleyin. İçerik kontrolleri, gerçekçi insan görüntülerini veya diğer kısıtlı materyalleri reddedebilir; herkese açık bir URL'nin kabul garantisi verdiğini varsaymayın.
Üretimden önce medya yükleme ve inceleme
APIMaster, görüntü dosyası yüklemelerini ve Seedance medya kütüphanesini destekler. Bunlar ayrı adımlardır: bir dosya yüklemek size indirilebilir bir URL verir; bu URL'yi kütüphaneye göndermek içerik incelemesini başlatır. Yalnızca onaylanmış bir kütüphane varlığı, bir üretim isteğinde asset:// ile referans gösterilebilir. Sıradan, kişi olmayan referans medyası hala bir kütüphane gönderimi olmadan doğrudan genel URL'leri kullanabilir.
Kütüphane, bir materyali yeniden kullanacağınızda veya orijinal URL'si geçici olduğunda özellikle kullanışlıdır. İnceleme başarılı olduktan sonra, döndürülen asset:// adresini yeniden kullanın; gelecekteki referanslar, orijinal URL'sini yeniden göndermenizi gerektirmek yerine onaylanmış materyali kullanır. Onu referans göstermeye ihtiyaç duyduğunuz sürece materyali kütüphanenizde saklayın.
Gerçek kişi medyası önce medya kütüphanesine gönderilmeli ve incelemeyi geçmelidir. Başarılı bir dosya yüklemesi, erişilebilir bir URL veya başarılı bir inceleme görevi gönderimi, materyalin onaylandığı anlamına gelmez. Yüklemeye ve kullanmaya yetkili olduğunuz medyayı kullanın. İnceleme onayı, her sonraki üretim isteğinin kendi içerik kontrollerinden geçeceğini garanti etmez.
Önerilen sıra şudur: genel bir dosya URL'sine ihtiyacınız varsa bir görüntü yükleyin → materyali inceleme için gönderin → inceleme görevini sorgulayın → bir Active varlığı seçin → video üretimini gönderin → video görevini sorgulayın. Her adımdan döndürülen kimlikleri kaydedin; video üretimi için belgelenmiş video sorgu uç noktalarını kullanın.
Materyal özellikleri ve hazırlık
Yukarıdaki referans medya tablosu kütüphane gönderimleri için de geçerlidir. Sadece uzantısını değil, gerçek kod çözülmüş dosyayı kontrol edin. Seedance 2.5 için:
| Materyal | Kabul edilen formatlar | Dosya limiti | Teknik gereksinimler |
|---|---|---|---|
| Görüntü | JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF; RGB JPEG/PNG önerilir | Kütüphane kaynağı başına 30 MB altında |
Genişlik ve yükseklik her biri 300–6000 piksel; genişlik/yükseklik oranı 0.4–2.5 |
| Video | MP4, MOV; H.264/H.265 video; mevcut olduğunda AAC/MP3 ses | Dosya başına en fazla 200 MB |
Her klip 2–30 saniye; düzenleme kaynağı 4–30 saniye; her kenar 300–6000 piksel; oran 0.4–2.5; toplam piksel 409600–8295044; kare hızı 24–60 FPS; desteklenen katmanlar 480p, 720p, 1080p |
| Ses | WAV, MP3 | Dosya başına en fazla 15 MB |
Her klip 2–30 saniye |
Bir inceleme gönderimi, bir türden 1–20 varlık içerir. Bu toplu limit, üretim limitlerinden farklıdır: en fazla 30 görüntü, 10 video veya 10 ses klibi; referans gösterilen videolar birlikte 30 saniyeyi aşmamalıdır ve referans gösterilen ses birlikte 30 saniyeyi aşmamalıdır. 20 materyal yüklemek, 20 videonun veya ses klibinin tek bir üretimde kullanılmasına izin vermez.
30 saniyeye kadar video kaynakları için açıkça model: "seedance-2.5" gönderin. Kütüphane gönderimi varsayılanı seedance-2.0'dir, bu da bireysel video kaynaklarını 15 saniye ile sınırlar. Onaylanmış materyaller, talep edilen modelin anahtarınıza uygun olduğu ve materyalin o modelin limitlerini karşıladığı durumlarda Seedance 2.0 ve 2.5 arasında yeniden kullanılabilir.
Ses kütüphanesine yükleme: resmî CreateAsset API’si 2–30 saniyelik WAV/MP3 kliplerini, dosya başına en fazla 15 MB olacak şekilde kabul eder. Üretim sınırları ayrıdır: Seedance 2.0 klip başına 2–15 saniye, en fazla 3 klip ve toplam 15 saniye; Seedance 2.5 klip başına 2–30 saniye, en fazla 10 klip ve toplam 30 saniye kabul eder. Onaylanmış materyaller de seçilen modelin üretim sınırlarına uymalıdır.
Video inceleme hataları: Bir inceleme isteğinin kabul edilmesi, bir videonun kullanılabilir olduğunu belirlemez. Bir inceleme FormatUnsupported veya Unsupported media format ile başarısız olabilir. Gerçek konteyneri, kodeği, boyutları, kare hızını, ses parçasını ve URL erişilebilirliğini kontrol edin; bir kütüphane videosunu yalnızca Active olduktan sonra referans gösterin. Gerçek kişi videoları, üretimden önce inceleme onayı gerektirir.
Oturum açma, çerezler, ek yetkilendirme başlıkları veya sıcak bağlantı engelleme kısıtlamaları olmadan doğrudan dosyayı indiren bir HTTP(S) URL'si kullanın. İmzalı URL'leri alım ve inceleme boyunca geçerli tutun ve içeriklerini değiştirmeden saklayın. Paylaşım sayfası HTML'i, süresi dolmuş bağlantılar, özel ağ adresleri, bozuk kodekler veya yanıltıcı dosya uzantıları redde neden olabilir. Video ve sesi kendi dosya depolamanıza yükleyin ve doğrudan URL'lerini gönderin; aşağıdaki görüntü dosyası yükleme uç noktası video veya ses kabul etmez.
Adım 1: yerel bir görüntü dosyası yükleyin
POST https://apimaster.ai/v1/uploads/images adresine file adlı bir alan içeren çok parçalı form verisi gönderin. Manuel olarak bir JSON içerik türü ayarlamayın: HTTP istemciniz çok parçalı sınırı sağlamalıdır.
curl --fail-with-body -sS "https://apimaster.ai/v1/uploads/images" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@./reference.png"
Örnek yanıt:
{
"url": "https://apimaster.ai/imgs/media_upload_example.png",
"filename": "reference.png",
"content_type": "image/png",
"bytes": 123456,
"created_at": 1790812800
}
Bu uç nokta yalnızca JPEG, PNG, GIF ve WebP'yi kabul eder, maksimum dosya boyutu 20 MiB'dir (20 × 1024 × 1024 bayt). Algılanan görüntü formatını ve okunabilir görüntü boyutlarını doğrular; başarılı bir yükleme her Seedance gereksinimini doğrulamaz veya içeriği onaylamaz. Bu yükleme limitinden daha büyük görüntüler ve bu listede bulunmayan kütüphane uyumlu formatlar için kendi genel dosya depolamanıza ihtiyacınız vardır.
Döndürülen URL APIMaster'ın alan adını kullanır ve URL'yi bilen herkes tarafından genel olarak okunabilir. Kalıcı arşiv depolama yerine API medya girişi için tasarlanmıştır; orijinal dosyanızı saklayın ve garanti edilmiş bir saklama süresi olduğunu varsaymayın. İndirme kimlik doğrulaması gerektirmesi gereken gizli içeriği yüklemeyin. URL'yi bir sonraki adımda veya kütüphane incelemesi gerekmediğinde doğrudan bir üretim isteğinde yeniden kullanın.
Adım 2: materyalleri inceleme için gönderin
POST https://apimaster.ai/v1/seedance2/private-avatar/assets adresine JSON gönderin. Ya yeni bir group ya da mevcut bir APIMaster group_id ayarlayın, asla ikisini birden değil. İkisini de atlamak otomatik olarak yeni bir grup oluşturur.
curl --fail-with-body -sS "https://apimaster.ai/v1/seedance2/private-avatar/assets" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5",
"group": {"name": "My reference materials", "description": "Approved generation references"},
"project_name": "default",
"asset_type": "Image",
"assets": [
{"url": "https://apimaster.ai/imgs/media_upload_example.png", "name": "reference-portrait"}
]
}'
Video veya ses için, aynı assets yapısında doğrudan URL'lerle asset_type: "Video" veya asset_type: "Audio" kullanın. Bir gönderim içinde türleri karıştırmayın.
| Alan | Tür | Gereksinim ve davranış |
|---|---|---|
model |
string | Bu kılavuz için seedance-2.5 kullanın; varsayılan seedance-2.0'dir |
group |
object | İsteğe bağlı yeni grup: 255 karaktere kadar name, 4000 karaktere kadar description |
group_id |
string | İsteğe bağlı mevcut grup kimliği APIMaster tarafından döndürülür; hesabınıza ait olmalıdır |
project_name |
string | İsteğe bağlı; şu anda yalnızca default desteklenir |
asset_type |
string | Büyük/küçük harfe duyarlı Image, Video veya Audio; varsayılan Image |
assets |
object[] | Seçilen türden 1–20 materyal içeren gerekli dizi |
assets[].url |
string | Gerekli genel HTTP(S) dosya URL'si; maksimum 8192 karakter |
assets[].name |
string | İsteğe bağlı görünen ad, 255 karaktere kadar; atlanırsa otomatik bir ad kullanılır |
Örnek kabul edilen yanıt:
{
"code": 200,
"data": {
"id": "asset_task_example",
"object": "seedance.avatar.asset.task",
"model": "seedance-2.5",
"status": "processing",
"progress": 0,
"group_id": "group_example"
}
}
data.id'u inceleme görev kimliği olarak ve data.group_id'u sonraki gönderimler için kaydedin. Bir HTTP başarı yanıtı yalnızca kabulü onaylar. Bir dosya adından veya görev kimliğinden bir varlık kimliği oluşturmayın.
Adım 3: inceleme görevini sorgulayın ve onaylanmış varlıkları seçin
data.status, completed veya failed olana kadar GET https://apimaster.ai/v1/tasks/{review_task_id} adresini her 5–10 saniyede bir sorgulayın. Bu uç nokta materyal inceleme görevi içindir; video üretimi için bu sayfada başka yerde belgelenmiş video uç noktalarını kullanın.
curl --fail-with-body -sS "https://apimaster.ai/v1/tasks/asset_task_example" \
-H "Authorization: Bearer YOUR_API_KEY"
Örnek tamamlanmış yanıt; zaman damgası ve kaynak URL alanları kısalık için burada atlanmıştır:
{
"code": 200,
"data": {
"id": "asset_task_example",
"object": "seedance.avatar.asset.task",
"model": "seedance-2.5",
"status": "completed",
"progress": 100,
"group_id": "group_example",
"result": {
"assets": [{"id": "asset_example", "asset_id": "asset_example", "asset_url": "asset://asset_example", "name": "reference-portrait", "asset_type": "Image", "group_id": "group_example", "status": "Active"}],
"usable_assets": [{"id": "asset_example", "asset_id": "asset_example", "asset_url": "asset://asset_example", "name": "reference-portrait", "asset_type": "Image", "group_id": "group_example", "status": "Active"}],
"failed_assets": []
}
}
}
İnceleme görev durumları processing, completed ve failed'dir. Materyal durumları Pending, Active ve Failed'dir; yalnızca Active materyaller referans gösterilebilir. Döndürülen asset_url'ü değiştirmeden kullanın. Bu, onaylanmış bir kütüphane materyalini tanımlar ve bir HTTP indirme URL'si değildir.
Bir toplu işlem kısmen başarılı olabilir. Bir reddedilmiş materyal, genel inceleme görevinin failed olmasına neden olabilirken diğer materyaller zaten Active olabilir. Görev başarısız olduğunda her öğeyi atmak yerine result.usable_assets ve result.failed_assets'u inceleyin. Materyal sonuçları mevcut olmadan önce bir başarısızlık, sonuç olmadan güvenli bir error mesajı döndürebilir. Yalnızca reddedilen girdileri düzeltin ve yeniden gönderin; kabul edilenleri tekrarlamaktan kaçının.
Kütüphane listesine güvenmeden önce inceleme görevini sorgulayın: listeler bekleyen inceleme görevlerini otomatik olarak sorgulamaz. Görev sorguları ve varlık detayları, sonraki istekler tarafından kullanılan genel materyal kimliklerini döndürür.
Adım 4: onaylanmış bir materyalle üretim yapın
Onaylanmış bir asset_url'yi, materyal türüyle eşleşen image_urls, image_with_roles[].url, video_urls veya audio_urls içinde kullanın. Bu ilk kare örneği onaylanmış görüntüyü kullanır:
{
"model": "seedance-2.5",
"prompt": "The person slowly turns toward the camera, natural lighting, gentle camera movement.",
"image_with_roles": [{"url": "asset://asset_example", "role": "first_frame"}],
"aspect_ratio": "adaptive",
"duration": 5,
"resolution": "720p",
"generate_audio": false
}
Bu JSON'ı POST https://apimaster.ai/v1/videos/generations adresine gönderin, ardından aşağıda açıklandığı gibi döndürülen video görevini sorgulayın. Bir hesap altında onaylanmış bir varlık başka bir hesap tarafından kullanılamaz. APIMaster tarafından döndürülen kimlikleri saklayın; başka bir servisten kopyalanan kimlikler çalışmaz. Bir istekte birleştirilen materyaller uyumlu bir kütüphane bağlamından gelmelidir; mevcut değilse, onları aynı APIMaster grubunda birlikte oluşturun ve incelemeden sonra yeniden deneyin. Bir materyali silmek, gelecekteki isteklerin ona referans göstermesini engeller.
Kütüphane varlıkları kullanan bir istek gönderilemiyorsa, durumunu ve görev geçmişinizi tekrar göndermeden önce kontrol edin. Özellikle bir ağ zaman aşımından sonra hemen yinelenen üretim isteklerinden kaçının.
Materyalleri listeleme, inceleme, yeniden adlandırma ve silme
Tüm uç noktalar bir APIMaster API anahtarı gerektirir. Kütüphane hesabınıza özgüdür, bu nedenle aynı hesaba ait anahtarlar kaynaklarına erişebilir; başka bir hesabın kaynakları HTTP 404 döndürür. Listeleme işlemleri yalnızca hesabınızın materyallerini ve gruplarını döndürür.
| Yöntem | Uç Nokta | Amaç |
|---|---|---|
POST |
https://apimaster.ai/v1/seedance2/private-avatar/groups |
model, name ve isteğe bağlı description kullanarak bir grup oluşturma |
GET |
https://apimaster.ai/v1/seedance2/private-avatar/groups |
Gruplarınızı listeleme |
GET |
https://apimaster.ai/v1/seedance2/private-avatar/groups/{group_id} |
Bir grubu inceleme |
PATCH |
https://apimaster.ai/v1/seedance2/private-avatar/groups/{group_id} |
name ve/veya description güncelleme |
DELETE |
https://apimaster.ai/v1/seedance2/private-avatar/groups/{group_id} |
Boş bir grubu silme |
POST |
https://apimaster.ai/v1/seedance2/private-avatar/assets |
Bir inceleme toplu işi gönderme |
GET |
https://apimaster.ai/v1/seedance2/private-avatar/assets |
Materyallerinizi listeleme |
GET |
https://apimaster.ai/v1/seedance2/private-avatar/assets/{asset_id} |
Bir materyali inceleme ve inceleme durumunu yenileme |
PATCH |
https://apimaster.ai/v1/seedance2/private-avatar/assets/{asset_id} |
Görünen name güncelleme |
DELETE |
https://apimaster.ai/v1/seedance2/private-avatar/assets/{asset_id} |
Bir materyali silme |
GET |
https://apimaster.ai/v1/tasks/{review_task_id} |
Bir inceleme görevini sorgulama |
Liste sorguları page (varsayılan 1) ve limit (varsayılan 20, aralık 1–100) kabul eder. Materyal listesi ayrıca group_id ve büyük/küçük harfe duyarlı bir status filtresi kabul eder. Yanıtı {"code":200,"data":{"items":[],"total":0,"page":1,"limit":20}}'dir; öğeler materyal/grup detaylarıyla aynı genel alanları kullanır. Liste sonuçları APIMaster dışında oluşturulan kaynakları içermez.
Örnekler:
# List approved materials in a group.
curl --fail-with-body -sS "https://apimaster.ai/v1/seedance2/private-avatar/assets?group_id=group_example&status=Active&page=1&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
# Rename one material without changing the source file.
curl --fail-with-body -sS -X PATCH "https://apimaster.ai/v1/seedance2/private-avatar/assets/asset_example" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"approved-reference"}'
# Delete a material before deleting its group.
curl --fail-with-body -sS -X DELETE "https://apimaster.ai/v1/seedance2/private-avatar/assets/asset_example" \
-H "Authorization: Bearer YOUR_API_KEY"
Grup oluşturma varsayılan olarak seedance-2.5'dir; netlik için açıkça model sağlayın. Görünen ad değişiklikleri materyal dosyasını değiştirmez veya incelemeyi tekrarlamaz. Medyayı değiştirmek için yeni bir inceleme gönderin. Henüz tamamlanmış bir incelemesi olmayan bekleyen materyaller yeniden adlandırılamaz veya silinemez ve HTTP 409 döndürür. Bir grubu silmeden önce gruptaki her materyali silin; boş olmayan gruplar HTTP 409 döndürür. Başarılı bir silme {"code":200,"data":{"id":"asset_example","deleted":true}} döndürür (bir grup silme işlemi grup kimliğini döndürür).
Ücretler, hız limitleri ve hatalar
Görüntü dosyası yükleme, materyal inceleme ve kütüphane CRUD işlemlerinin üretim ücreti yoktur ve video kullanımı faturalama kayıtları oluşturmaz. Onaylanmış materyaller kullanılarak video üretimi, seçilen modele ve referanslara göre normal şekilde faturalandırılır. Ücretsiz kütüphane işlemleri hala geçerli bir yetkili anahtar gerektirir ve API anahtarı/model hız limitlerine tabidir. Yükleme ve oluşturma uç noktaları ayrıca IP başına istekleri sınırlar; büyük patlamalar göndermek yerine boşluk isteyin.
| HTTP durumu | Anlamı | Önerilen eylem |
|---|---|---|
400 |
Geçersiz JSON, alanlar, URL, görüntü verisi, tür veya toplu iş boyutu | Şemayı ve gerçek dosya özelliklerini kontrol edin |
401 / 403 |
Eksik/geçersiz anahtar veya yetersiz model izni | APIMaster anahtarınızı ve izin verilen modelleri doğrulayın |
404 |
Bilinmeyen, silinmiş veya erişilemez materyal/grup/inceleme görevi | Aynı hesaba döndürülen kimlikleri kullanın |
400 / 409 |
Materyal henüz hazır değil, uyumsuz materyal bağlamı veya boş olmayan grup | İncelemeyi tamamlayın, uyumlu bir grup kullanın veya grup üyelerini kaldırın |
413 |
Görüntü yükleme dosya/gövde boyutu limitini aşıyor | Dosya boyutunu azaltın veya kendi genel depolamanızı kullanın |
429 |
İstek hız limitine ulaşıldı | Eşzamanlılığı azaltın ve sorguları geri çekilme ile yeniden deneyin |
502 / 503 |
İnceleme servisi kullanılamıyor veya geçersiz yanıt | Önce sorguları yeniden deneyin; mevcut görev ve materyal kimliklerini saklayın |
Bir inceleme görevi HTTP 200 ile data.status: "failed" döndürebilir; yalnızca HTTP koduna güvenmek yerine görev durumunu ve güvenli hata mesajını inceleyin. Döndürülen açıklamayı okuyun ve destek için genel inceleme görev kimliğini saklayın.
Medya kütüphanesi SSS
- İnceleme ne kadar sürer? Her
5–10saniyede bir sorgulayın. Süre materyale ve servis iş yüküne göre değişir; video ve gerçek kişi incelemesi görüntü incelemesinden daha uzun sürebilir. Kabul edilen bir gönderim onay değildir. - İnceleme bir açıklama olmadan başarısız olursa ne olur? İnceleme görevini ve
failed_assets'u inceleyin; destek için genel görev/varlık kimliklerini saklayın. Düzeltilmiş materyali göndermeden önce formatı ve URL erişilebilirliğini kontrol edin. Bir sorgu başarısız bir incelemeyi yeniden başlatmaz. - 2.0'a karşı 2.5 için tekrar yüklemeli miyim? Onaylanmış bir APIMaster varlığı, anahtarınızın hedef modele erişimi olduğunda ve materyal o modelin limitlerini karşıladığında yeniden kullanılabilir. Platformlar arası kimlikler yeniden kullanılamaz.
- Bir toplu işlem kısmen başarılı olabilir mi? Evet. Yalnızca durumu
Activeolanusable_assets'yi yeniden kullanın; reddedilen öğeleri ayrı ayrı düzeltin. - Senkron bir materyal hatası ne anlama gelir? HTTP 400 geçersiz girdiyi reddeder.
invalid_asset_material,assets[0],assets[1]vb. tanımlayabilir; indeksler sıfırdan başlar. Belirtilen öğenin formatını veya süresini düzeltin ve tekrar gönderin.
{
"error": {
"message": "invalid_asset_material: assets[0] video duration must be from 2 to 30 seconds",
"type": "media_library_error"
}
}
Önizleme modu: 480p taslak'tan 1080p final'e
Bir önizleme, draft: true ile normal faturalanabilir bir oluşturmadır. Önizleme görevinin oluşturulma zamanından itibaren 7 gün boyunca yükseltmeler için geçerlidir. Her yükseltme bağımsız bir görev ve ücrettir; aynı süresi dolmamış başarılı önizleme birden çok kez yükseltilebilir.
Adım 1: bir önizleme oluşturun ve durumunu sorgulayın
curl --fail-with-body -sS "https://apimaster.ai/v1/videos/generations" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"seedance-2.5","prompt":"A colorful abstract pattern gently moves.","draft":true,"duration":5,"return_last_frame":true}'
Belirtilmeyen çözünürlük 480p olur. draft: true ile 720p veya 1080p göndermek 400 hatası döndürür. Döndürülen genel kimliği /v1/videos/{task_id} veya /v1/video/generations/{task_id} üzerinden sorgulayın ve yükseltmeden önce başarılı olmasını bekleyin. Diğer oluşturma parametreleri ve medya sınırları normal şekilde uygulanır.
Adım 2: önizlemeden bir final videosu oluşturun
curl --fail-with-body -sS "https://apimaster.ai/v1/videos/generations" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"seedance-2.5","draft_task_id":"task_preview_example","output_format":"mp4","return_last_frame":true,"watermark":false}'
Yanıt yeni bir genel görev kimliği içerir. Belirtilmeyen çözünürlük 1080p olur; diğer tüm çözünürlük değerleri 400 döndürür. Önizlemenin hesabına ait bir API anahtarı kullanın. Eksik, yabancı, önizleme olmayan, tamamlanmamış, süresi dolmuş veya farklı modelde bir görev, senkron olarak 400 hatasıyla reddedilir, bir görev oluşturulmaz veya rezervasyon ücreti alınmaz.
Önizleme geçici olarak kullanılamıyorsa, daha sonra aynı draft_task_id ile tekrar deneyin. Başka bir platformun kimliği ile değiştirmeyin. Bir önizleme yükseltmesi farklı bir oluşturma bağlamına yönlendirilemez.
Miras alınan alanlar ve izin verilen değişiklikler
Değerleri aynı olsa bile, false, 0 veya null olsalar bile, miras alınan alanları tekrar göndermeyin:
prompt, image_urls, image_with_roles, video_urls, audio_urls, duration, size, aspect_ratio, ratio, seed, generate_audio, audio, omni_reference_task_type, generation_type, camerafixed, web_search, tools.
Aynı kısıtlama APIMaster'ın girdi takma adları ve eski sarmalayıcı için de geçerlidir: seconds, images, image, input_reference, first_frame_image, last_frame_image, video_list, negative_prompt, metadata.
model, draft_task_id ve sabit 1080p çözünürlüğü dışında, ayarlanabilir alanlar yalnızca output_format, return_last_frame ve watermark'dir. Belirtilmeyen değerler sırasıyla mp4, false ve false kullanır. Son kare ve filigran bayrakları önizlemeden miras alınmaz. draft_task_id ile draft: true'ü birleştirmeyin. Hem önizleme oluşturma hem de yükseltme service_tier'ü reddeder.
Önizleme ve final-video rezervasyonları
| Önizleme süresi | Önizleme rezervasyonu | Final-video rezervasyonu |
|---|---|---|
Açıkça belirtilen 4–30 saniye |
Belirtilen süre 480p'de; referans-video işi normal şekilde dahil | Video girdisi olmadan aynı süre 1080p katmanında |
-1, edit'de belirtilmeyen süre dahil |
Maksimum 30 saniyeye kadar | Video girdisi olmadan 1080p'de 30 saniyeye kadar |
| Diğer belirtilmeyen süre | 480p'de 5 saniye | Video girdisi olmadan 1080p'de 5 saniye |
Önizleme işi normal 480p fiyatlandırmasını takip eder; referans-video süresi normal şekilde sayılır ve birleşik faturalanabilir süre 30 saniye ile sınırlıdır. Final-video işi, önizlemenin referans-video süresi hariç, video girdisi olmadan 1080p katmanını kullanır. Başarı, gerçek kullanımı mutabakata bağlar ve farkı iade eder veya tahsil eder; başarısızlık tam rezervasyonu iade eder. Fiyatlandırma model kartınızdan ve cüzdan kayıtlarınızdan gelir.
Üretim hizmetinin moderasyon politikası
"Moderation":{"Strategy":"Skip"} yalnızca açıkça destekleyen hizmetlerde kullanılabilir. Alan verilmezse hizmetin varsayılan politikası uygulanır. Materyal istekleri uyumlu bir group_id belirtmelidir. Desteklenmeyen strateji veya hizmetler hata döndürür; her istekte incelemenin atlanabileceğini varsaymayın.
moderation.requested istenen stratejiyi, moderation.forwarded ise geçerli yanıt alınan iletimi kaydeder. moderation.provider_effect_confirmed=false, etkinin doğrulanmadığını belirtir. Active, isteğin kabulü veya başarılı üretim, incelemenin kapatıldığını kanıtlamaz. Eski materyallerde bu alanların olmaması kullanılan stratejiyi göstermez.
Sorgu durumu ve indirme
Aynı görev her iki sorgu biçimi üzerinden okunabilir. Her 5–10 saniye gibi makul bir aralıkla sorgulayın ve terminal bir durumda durun. Üretim süresi iş yüküne, klip süresine, çözünürlüğe ve referanslara bağlıdır; yavaş bir görevi, yinelenen görevler oluşturmak için bir neden olarak ele almayın.
curl --fail-with-body -sS "https://apimaster.ai/v1/video/generations/task_example" \
-H "Authorization: Bearer YOUR_API_KEY"
curl --fail-with-body -sS "https://apimaster.ai/v1/videos/task_example" \
-H "Authorization: Bearer YOUR_API_KEY"
curl --fail-with-body -L "https://apimaster.ai/v1/videos/task_example/content" \
-H "Authorization: Bearer YOUR_API_KEY" \
-o output.mp4
Tamamlanan yanıtlar
Uyumluluk biçimi, GET /v1/video/generations/{task_id}:
{
"code": "success",
"message": "",
"data": {
"task_id": "task_example",
"status": "succeeded",
"url": "https://apimaster.ai/v1/videos/task_example/content",
"format": "mp4",
"error": null,
"metadata": null,
"usage": {"completion_tokens": 108900},
"actual_time": 160,
"last_frame_url": "https://apimaster.ai/v1/videos/task_example/last-frame"
}
}
OpenAI tarzı biçim, GET /v1/videos/{task_id}:
{
"id": "task_example",
"object": "video",
"model": "seedance-2.5",
"status": "completed",
"progress": "100%",
"url": "https://apimaster.ai/v1/videos/task_example/content",
"usage": {"completion_tokens": 108900},
"actual_time": 160,
"last_frame_url": "https://apimaster.ai/v1/videos/task_example/last-frame"
}
| Anlamı | Uyumluluk konumu | OpenAI tarzı konum |
|---|---|---|
| Genel görev kimliği | data.task_id |
id |
| Bekliyor | data.status: queued |
status: queued |
| Üretiliyor | data.status: processing |
status: in_progress |
| Başarılı | data.status: succeeded |
status: completed |
| Başarısız | data.status: failed |
status: failed |
| Video indirme URL'si | data.url |
url |
| Tamamlama token'ları | data.usage.completion_tokens |
usage.completion_tokens |
| Geçen saniye | data.actual_time |
actual_time |
| Son kare görsel URL'si | data.last_frame_url |
last_frame_url |
| Başarısızlık açıklaması | data.error.message |
error.message |
| Çıktı konteyneri | data.format |
Kaydederken talep edilen output_format kullanın |
| Eski metadata | data.metadata, şu anda null |
Kullanılmıyor |
actual_time, gönderim zamanından çıkarılan tamamlama zamanıdır, saniye cinsinden, bekleme süresi dahil; videonun süresi değildir. usage.completion_tokens kaydedilmiş üretim istatistiğidir ve tüketim kaydının token sayısıyla eşleşir. APIMaster'ın parasal mutabakatı video süresi ve geçerli kademesini kullanır; token istatistiği parasal bir fiyat formülü değildir. Yanıtlar miktar alanları içermez; mutabakat için cüzdanınızın tüketim kayıtlarını kullanın.
Kullanım tamamlanmanın hemen ardından eksik olabilir; daha sonra tekrar sorgulayın. last_frame_url yalnızca başarı durumunda ve siz return_last_frame: true talep ettiğinizde ve bir son kare mevcutsa döndürülür. Alan, talep edilmediğinde, hala bekliyorken veya başarısız olduğunda null olarak ayarlanmaz, ihmal edilir. Önizleme yükseltmeleri kendi bayraklarını kullanır.
Başarısız yanıt
Başarısız bir görev hala HTTP 200 ile sorgulanır. OpenAI tarzı yanıt şunları içerebilir:
{
"id": "task_example",
"object": "video",
"model": "seedance-2.5",
"status": "failed",
"progress": "100%",
"error": {"code": "task_failed", "message": "[upstream_error] Unsupported media format."}
}
Uyumluluk biçimi açıklamayı data.error.message konumuna yerleştirir. Başarısız görevlerde video veya son kare indirmesi yoktur. Destek için genel görev kimliğini ve açıklamayı saklayın.
Video ve son kareyi indirme
Her iki URL'yi indirirken de Authorization: Bearer YOUR_API_KEY gönderin. Görevin hesabına ait bir anahtar kullanın. Video içeriği talebe göre MP4 veya MOV'dur; MOV'u .mov uzantısıyla kaydedin. Son kare bir görseldir, bu nedenle uzantısını seçerken döndürülen içerik türünü kullanın.
curl --fail-with-body -L "https://apimaster.ai/v1/videos/task_example/last-frame" \
-H "Authorization: Bearer YOUR_API_KEY" \
-o last-frame.jpg
Başarılı dosyaları derhal indirin ve kaydedin. Kullanılabilirlik süresiz değildir; bir görev kimliğini saklamak, çıktı dosyasının indirilebilir kalacağını garanti etmez. Dosya artık mevcut değilse, indirme HTTP 410 ile error.message: "Media has expired or is no longer available" döndürür. Mevcut olmayan veya talep edilmemiş bir son kare HTTP 404 döndürür. Eksik indirme kimlik doğrulaması HTTP 401 döndürür.
Python: gönder, sorgula ve kaydet
import os
import time
import requests
base = "https://apimaster.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['APIMASTER_API_KEY']}"}
payload = {
"model": "seedance-2.5",
"prompt": "A lighthouse above a calm sea, slow camera push-in, no text.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "adaptive",
"generate_audio": True,
"watermark": False,
"return_last_frame": True,
}
response = requests.post(f"{base}/videos/generations", headers=headers,
json=payload, timeout=60)
response.raise_for_status()
created = response.json()
data = created.get("data")
if isinstance(data, list) and data:
task_id = data[0].get("task_id")
else:
item = data if isinstance(data, dict) else created
task_id = item.get("task_id") or item.get("id")
if not task_id:
raise RuntimeError("No task ID returned; inspect the submission response.")
print("task_id:", task_id)
# Example client timeout, not a promised generation deadline.
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
response = requests.get(f"{base}/videos/{task_id}", headers=headers, timeout=60)
response.raise_for_status()
task = response.json()
state = task.get("status")
if state == "failed":
error = task.get("error") or {}
raise RuntimeError(error.get("message", "Video generation failed."))
if state == "completed":
result = requests.get(f"{base}/videos/{task_id}/content", headers=headers,
timeout=120, stream=True)
result.raise_for_status()
with open("output.mp4", "wb") as output:
for chunk in result.iter_content(1024 * 1024):
if chunk:
output.write(chunk)
print("Saved output.mp4")
print("usage:", task.get("usage"), "actual_time:", task.get("actual_time"))
if task.get("last_frame_url"):
frame = requests.get(task["last_frame_url"], headers=headers, timeout=60)
frame.raise_for_status()
with open("last-frame.jpg", "wb") as image:
image.write(frame.content)
print("Saved last-frame.jpg")
break
time.sleep(5)
else:
raise TimeoutError(f"Task {task_id} is still pending; keep this ID and query it later.")
Gönderim sırasında bir bağlantı zaman aşımı, sonucu belirsiz bırakır: döndürülen herhangi bir görev kimliğini saklayın ve tekrar göndermeden önce görev geçmişinizi kontrol edin. Bir sorgulama zaman aşımı bir görevi iptal etmez. Kabul edilip edilmediğini bilmediğiniz faturalandırılabilir bir gönderimin otomatik yeniden denemelerinden kaçının.
Faturalandırma, rezervasyonlar ve iadeler
Faturalandırma saniye cinsinden süre kullanır ve çözünürlüğe, girdi-ortam türüne ve hesabınızın geçerli fiyatına bağlıdır. Üretilen ve sessiz ses, mevcut Seedance 2.5 yapılandırmasında ayrı bir fiyatlandırma kademesi seçmez. Gönderimden önce model kartını ve cüzdanın video/ortam fiyatlandırmasını kontrol edin; bu sayfa değişen bir fiyatı sabit kodlamaz.
- Gönderim tahmini bir miktarı rezerve eder. Atlanmış sıradan süre
5saniye rezerve eder.duration: -1için tahmin,30saniyelik maksimumu kullanır, bu nedenle sonuç daha kısa olsa bile yeterli bakiye gereklidir. - Referans videoyla, faturalandırılabilir iş referans-video süresi artı üretilen-video süresini içerebilir.
5saniyelik bir çıktı mutlaka yalnızca5saniyelik iş olarak faturalandırılmaz. - Başarılı üretimden sonra, nihai ölçülen kullanım ek bir ücret veya farkın iadesi üretebilir. Mutabakatı onaylamak için nihai cüzdan kayıtlarını kullanın.
- Başarısız görevler üretim rezervasyonunu iade eder. Başarısız bir görev, hala orijinal tüketim kaydını eşleşen bir iadeyle birlikte gösterebilir; net ücreti kontrol ederken her ikisini de sayın.
- Geçersiz bir talebi düzeltmek yeni bir gönderim gerektirir. Mevcut başarısız bir görev kimliği, ona sorgulamaya devam edilerek yeniden başlatılamaz.
Gönderim hatalarından sonra güvenli yeniden deneme
Hata veya zaman aşımından sonra önce idempotent kabul kaydını sorgulayın. Düzeltilmiş parametreleri yalnızca new_submission_safe=true ise yeni bir Idempotency-Key ile gönderin; eski anahtar yalnızca ilk kaydı döndürür. acceptance_unknown veya new_submission_safe=false durumunda tekrar göndermeyin. HTTP 400 veya receipt_not_found tek başına kabul ya da ücretlendirmeyi kanıtlamaz; kabul ve fatura kayıtlarını kontrol edin.
JavaScript, Go, Java ve PHP örnekleri
Bu örnekler bir metinden-videoya görevi gönderir ve yanıtını yazdırır. data[0].task_id kaydedin, ardından yukarıdaki sorgu/indirme akışını kullanın. Anahtarınızı sunucu ortamından okuyun.
JavaScript (Node.js)
const response = await fetch("https://apimaster.ai/v1/videos/generations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.APIMASTER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "seedance-2.5", prompt: "A lighthouse at sunrise, slow camera push-in.",
duration: 5, resolution: "720p", aspect_ratio: "adaptive",
generate_audio: true, watermark: false, output_format: "mp4",
}),
});
const body = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${body}`);
console.log(JSON.parse(body));
Go
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
"time"
)
func main() {
payload, err := json.Marshal(map[string]any{
"model": "seedance-2.5", "prompt": "A lighthouse at sunrise, slow camera push-in.",
"duration": 5, "resolution": "720p", "aspect_ratio": "adaptive",
"generate_audio": true, "watermark": false, "output_format": "mp4",
})
if err != nil { panic(err) }
req, err := http.NewRequest("POST", "https://apimaster.ai/v1/videos/generations", bytes.NewReader(payload))
if err != nil { panic(err) }
req.Header.Set("Authorization", "Bearer " + os.Getenv("APIMASTER_API_KEY"))
req.Header.Set("Content-Type", "application/json")
response, err := (&http.Client{Timeout: 60 * time.Second}).Do(req)
if err != nil { panic(err) }
defer response.Body.Close()
body, err := io.ReadAll(response.Body)
if err != nil { panic(err) }
if response.StatusCode >= 400 { panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, body)) }
fmt.Println(string(body))
}
Java (JDK 11+)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
public class SeedanceExample {
public static void main(String[] args) throws Exception {
String json = "{\"model\":\"seedance-2.5\",\"prompt\":\"A lighthouse at sunrise.\","
+ "\"duration\":5,\"resolution\":\"720p\",\"aspect_ratio\":\"adaptive\","
+ "\"generate_audio\":true,\"watermark\":false,\"output_format\":\"mp4\"}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://apimaster.ai/v1/videos/generations"))
.timeout(Duration.ofSeconds(60))
.header("Authorization", "Bearer " + System.getenv("APIMASTER_API_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json)).build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() >= 400) {
throw new RuntimeException("HTTP " + response.statusCode() + ": " + response.body());
}
System.out.println(response.body());
}
}
PHP
<?php
$payload = [
'model' => 'seedance-2.5', 'prompt' => 'A lighthouse at sunrise, slow camera push-in.',
'duration' => 5, 'resolution' => '720p', 'aspect_ratio' => 'adaptive',
'generate_audio' => true, 'watermark' => false, 'output_format' => 'mp4',
];
$handle = curl_init('https://apimaster.ai/v1/videos/generations');
curl_setopt_array($handle, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('APIMASTER_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
]);
$body = curl_exec($handle);
if ($body === false) { throw new RuntimeException(curl_error($handle)); }
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);
if ($status >= 400) { throw new RuntimeException("HTTP $status: $body"); }
print_r(json_decode($body, true, 512, JSON_THROW_ON_ERROR));
Başka bir Seedance 2.5 entegrasyonundan geçiş
Temel URL'nizi https://apimaster.ai/v1 olarak ayarlayın ve gönderimleri POST /v1/videos/generations adresine yapın. Mevcut bir entegrasyonu geçirirken bu sayfanın APIMaster alan tanımlarını ve varsayılanlarını kullanın; süre, oran ve sesi açıkça belirtmeye devam edin.
Videolar için GET /v1/video/generations/{task_id} veya GET /v1/videos/{task_id} kullanın. /v1/tasks/{id} aynı zamanda medya inceleme görevleri için de kullanılır; bir APIMaster video ID'si için uyumluluk video yanıtını döndürür. Video ve inceleme işlemlerini net tutmak için iki özel video endpoint'ini tercih edin.
| Diğer entegrasyon | APIMaster uyumluluğu | APIMaster OpenAI stili |
|---|---|---|
pending |
data.status: queued |
status: queued |
processing |
data.status: processing |
status: in_progress |
completed |
data.status: succeeded |
status: completed |
failed |
data.status: failed |
status: failed |
data.result.videos[].url[0] |
data.url |
url |
| Son kare sonucu | data.last_frame_url |
last_frame_url |
| Üretim kullanımı | data.usage.completion_tokens |
usage.completion_tokens |
| Geçen süre | data.actual_time |
actual_time |
Video ve son kare URL'lerini hesabınızın Bearer anahtarıyla indirin. APIMaster miktar alanları döndürmez; cüzdan tüketim kayıtlarını kullanın. Görev ID'leri, asset:// ID'leri ve draft_task_id APIMaster'a özgüdür ve platformlar arasında kopyalanamaz. Materyallerinizi APIMaster'da tekrar gönderin ve inceleyin. Çıktıları başka bir hizmetin saklama süresinin geçerli olduğunu varsaymak yerine derhal kaydedin.
Seedance 2.0 ve 2.5 farklılıkları
Modelleri değiştirirken belirli modelin dokümantasyonunu kullanın. Limitler bir modelin sürüm numarasından çıkarılmaz.
| Yetenek | Seedance 2.0 | Seedance 2.5 |
|---|---|---|
| Genel model | seedance-2.0 |
seedance-2.5 |
| Varsayılan süre | 4 saniye |
5 saniye; düzenleme varsayılanı -1 |
| Üretim süresi | 4–15 s |
4–30 saniye veya -1 |
| Çözünürlük | 480p, 720p, 1080p, 4K |
480p, 720p, 1080p |
| Görsel/video/ses sayısı ve toplam süre | 2.0 modelinin medya limitlerini takip edin | 30 görsel, en fazla toplam 30 saniye olan 10 video, en fazla toplam 30 saniye olan 10 ses klibi |
| Saf ses referansı | 2.0 modelinin belgelenmiş modunu takip edin | Desteklenir |
| Çıktı formatı | mp4, mov |
mp4, mov |
| Filigran | 2.0 modelinin belgelenmiş seçeneklerini takip edin | Varsayılan olarak false |
| Önizleme ve yükseltme | Bu iş akışı tarafından desteklenmez | 480p önizleme → 1080p final; 7 gün geçerlidir |
| Medya kütüphanesi video alımı varsayılanı | Tek video limiti 15 saniye |
Açıkça seçildiğinde tek video limiti 30 saniye |
| Medya kütüphanesi ses alımı | 2–30 saniye |
2–30 saniye |
Onaylanmış asset:// referansları |
Aynı hesabın onaylanmış varlıkları, model izinleri ve limitlere tabi | Aynı kural; platformlar arası ID'ler kabul edilmez |
Hata yanıt yapıları
Gönderim doğrulaması HTTP 400 ile bir error nesnesi döndürür:
{
"error": {
"message": "draft resolution must be 480p",
"type": "invalid_request_error"
}
}
Bazı istek-reddetme yolları, moderasyon ve geçersiz medya girdileri de dahil olmak üzere bir code / message / data zarfı kullanır:
{
"code": "invalid_request",
"message": "Invalid format for image_with_roles[0].url. Only http/https URLs or asset:// private asset URLs are supported.",
"data": null
}
Eksik indirme kimlik doğrulaması HTTP 401 döndürür:
{
"error": {
"code": "",
"message": "Invalid token (request id: request_example)",
"type": "new_api_error"
}
}
Her iki hata zarfını da işleyin: mevcut olduğunda error.message'yi okuyun, aksi takdirde message'yi okuyun. Başarısızlığı tespit etmek için tek bir hata kodu alanı gerektirmeyin. Bir video sorgusu HTTP 200 yanıtı hala başarısız bir görev içerebilir.
| Gönderim mesajı | Anlamı |
|---|---|
unsupported seedance-2.5 resolution "4k" |
Desteklenen bir çözünürlük kullanın |
seedance-2.5 duration must be -1 or an integer from 4 to 30 |
İzin verilen aralığın dışında süre |
first/last frame aspect_ratio must be adaptive |
Yalnızca görsel kare görevi sabit bir oran kullanır |
edit requires at least one video_urls entry |
Eksik düzenleme kaynağı |
extend requires at least one video_urls entry |
Eksik uzatma kaynağı |
edit duration must be -1 |
Açık düzenleme süresi otomatik değildir |
draft resolution must be 480p |
Önizleme çözünürlüğü geçersiz |
draft_task_id resolution must be 1080p |
Yükseltme çözünürlüğü geçersiz |
draft and draft_task_id cannot be used together |
Birbirini dışlayan önizleme alanları |
service_tier is not supported for draft tasks |
Önizleme veya yükseltme için zamanlama alanı sağlandı |
draft_task_id was not found in your account |
Eksik veya erişilemez önizleme ID'si |
draft_task_id is not a draft task |
Sıradan görev önizleme olarak sağlandı |
draft_task_id has not completed successfully |
Önizleme bekliyor veya başarısız oldu |
draft_task_id has expired; drafts are valid for 7 days |
Önizleme 7 günden eski |
draft_task_id model does not match |
Kaynak model farklı |
Draft is temporarily unavailable; retry with the same draft_task_id later |
Önizleme ID'sini değiştirmeden daha sonra tekrar deneyin |
prompt must not be supplied with draft_task_id |
Miras alınan alan yeniden gönderildi; eşdeğer hatalar diğer yasaklanmış alanları adlandırır |
Sorun Giderme
Senkron bir gönderim hatasını asenkron bir başarısızlıktan ayırt edin: HTTP 200 yanıtı yalnızca bir görev ID'si içeriyorsa, bu sadece kabul edildiğini onaylar. Görev daha sonra failed durumuna geçebilir.
| Hata veya belirti | Olası neden | Yapılacaklar |
|---|---|---|
Geçersiz ratio / ilk kare oranı görseli takip etmeli |
Bir kare görevinde sabit oran kullanıldı | aspect_ratio: "adaptive" ayarlayın; belirli bir oran gerekiyorsa ilk görseli kırpın/kenar ekleyin |
Geçersiz content[1] / geçersiz görsel formatı |
Bir URL HTML döndürüyor, süresi dolmuş bir bağlantı veya desteklenmeyen/deşifre edilemeyen bir görsel | Doğrudan dosya URL'sini giriş yapmadan açın; JPEG/PNG'ye dönüştürün; boyutları doğrulayın ve yeni bir görevle tekrar deneyin |
| Görsel kenarı veya en-boy oranı aralık dışında | Bir görsel çok küçük/büyük veya çok geniş/dar | Her kenar 300–6000 piksel; genişlik/yükseklik 0.4–2.5 |
InvalidParameter.TaskTypeConstraint |
Düzenleme/genişletme/kare ayarları, göreve özgü sözleşmeyi ihlal ediyor | adaptive kullanın; düzenleme için ayrıca duration: -1 gerekir |
InvalidParameter.TaskTypeMismatch |
Bildirilen görev türü ve prompt amacı uyuşmuyor | Prompt'u yeniden yazın ve eşleşen bir omni_reference_task_type seçin |
| İçerik reddedildi / moderasyon engelledi | Girdi veya prompt uygulanabilir içerik kurallarını ihlal ediyor | Uyumlu medya kullanın ve prompt'u gözden geçirin; aynı reddedilmiş içeriği değiştirmeden tekrar denemeyin |
HTTP 400 |
Eksik prompt, desteklenmeyen çözünürlük/süre, geçersiz medya veya çakışan takma adlar | Yeniden göndermeden önce isteği bu sayfaya göre kontrol edin |
HTTP 401 / 403 |
Geçersiz anahtar veya yetersiz yetkilendirme | Görevin sahibi olan hesaptan alınan aktif bir APIMaster anahtarı kullanın |
Yetersiz bakiye, HTTP 402 veya bakiye/kota hatası dahil |
Mevcut cüzdan/anahtar tahsisi rezervasyonu karşılayamıyor | Cüzdan bakiyesini, anahtar tahsisini ve otomatik-süre rezervasyonunu kontrol edin |
HTTP 429 |
Oran veya eşzamanlılık limiti | Geri çekilin; sorgulama yaparken mevcut görev ID'sini yeniden kullanın |
HTTP 500 / 502 / ağ zaman aşımı |
Geçici servis veya bağlantı hatası | Geri çekilme ile okumaları tekrar deneyin; bir gönderimi yeniden denemeden önce görev geçmişini kontrol edin |
| Görev tamamlandı ancak indirme başarısız | Çok erken indirme, eksik kimlik doğrulama veya mevcut olmayan çıktı | Durumu tekrar sorgulayın, aynı hesabın anahtarını gönderin ve destek için görev ID'sini saklayın |
Kullanıcı görev günlüğü ve kullanım günlüğü ayrıntıları, güvenli başarısızlık açıklamalarını gösterir. Destekle iletişime geçerken, genel görev ID'sini, yaklaşık gönderim zamanını, modeli, çözünürlüğü, süreyi ve ilgili hata mesajını ekleyin. API anahtarınızı veya yetkilendirme başlığınızı asla göndermeyin.
İlgili: Video API'ye genel bakış · Seedance 2.0
Seedance teklifleri ve fatura makbuzları
Seedance teklifleri ve fatura makbuzları
