Seedance API

Rozhraní API umožňuje programaticky odesílat úlohy generování videa pro modely Seedance 2.5 a Seedance 2.0. Doporučeným modelem je Seedance 2.5, který podporuje převod textu na video, převod obrázku na video (z prvního snímku nebo z prvního a posledního snímku) a multimodální převod referencí na video. Generování probíhá asynchronně: vytvoříte úlohu, okamžitě obdržíte její ID a hotové video pak získáte buď dotazováním (polling) na koncový bod úlohy, nebo prostřednictvím webhooku.

Vytvořte si API klíč v dashboardu a posílejte jej v každém požadavku jako Bearer token. Celý klíč se zobrazí pouze jednou při jeho vytvoření.

Authorization: Bearer sk_live_xxxxxxxx

Nejprve odešlete úlohu. Po jejím přijetí zvolte jeden ze způsobů doručení výsledku: dotazujte se na koncový bod úlohy, nebo přijměte konečný výsledek přes webhook.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

curl https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

Vytvořte video úlohu pomocí POST /v1/videos/generations. Tělo požadavku obsahuje parametr model na nejvyšší úrovni, volitelný callback_url a objekt input s promptem a nastavením generování.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

Parametr generation_type určuje, jaké mediální vstupy jsou přijímány a jak je model interpretuje.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cinematic drone shot over a futuristic coastal city at sunrise",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "input": {
      "prompt": "the subject turns toward camera, soft studio motion",
      "generation_type": "image-to-video",
      "image_urls": ["https://your.cdn.com/first-frame.jpg"],
      "duration": 5,
      "resolution": "720p"
    }
  }'

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "input": {
      "prompt": "use the product from image 1 and the camera motion from the reference video",
      "generation_type": "reference-to-video",
      "image_urls": ["https://your.cdn.com/product.jpg"],
      "video_urls": ["https://your.cdn.com/camera-motion.mp4"],
      "audio_urls": [],
      "duration": 8,
      "resolution": "720p"
    }
  }'

Názvy parametrů, hodnoty enumů, cesty ke koncovým bodům a příklady jsou pevnou součástí API kontraktu. Níže uvedené popisy vysvětlují chování jednotlivých polí.

Toto je úspěšná odpověď z POST /v1/videos/generations. Znamená to, že úloha byla přijata a kredity byly rezervovány. Použijte vrácené taskId pro dotazování přes GET /v1/tasks/:id nebo pro párování se zpětným voláním o dokončení či selhání.

{
  "taskId": "3f2aK9mR...",
  "credits": 100
}

Pro získání aktuálního stavu úlohy použijte GET /v1/tasks/:id. Dotazujte se maximálně jednou za 10 sekund. V produkčních systémech dávejte přednost webhookům.

curl https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": ["https://cdn.seevio.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

Pokud je nastaven parametr callback_url, Seedance po dokončení nebo selhání úlohy zavolá váš koncový bod a odešle JSON data s výsledkem. Pokud váš koncový bod vrátí jiný kód než 2xx nebo neodpoví do 15 sekund, pokus o doručení se opakuje až 5krát. Opakované pokusy používají stejné task id, proto odstraňujte duplicity podle ID. Jakmile data z webhooku bezpečně uložíte, ihned vraťte odpověď s kódem 200.

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "data": {
    "results": ["https://cdn.seevio.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 100
  }
}

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

POST /v1/videos/generations a GET /v1/tasks/:id vrací tuto chybovou strukturu v případě, že selže samotný požadavek na API (např. neplatné parametry, neplatný API klíč, nedostatek kreditů, překročení limitu požadavků nebo nenalezení úlohy). Některé chyby obsahují další pole jako required, available nebo retry_after v závislosti na situaci.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this task.",
    "required": 100,
    "available": 12
  }
}

Limity četnosti se uplatňují na každý API klíč v klouzavém okně. Pro generování je výchozí limit 100 požadavků za minutu; dotazy na stav jsou benevolentnější. Odpovědi HTTP 429 obsahují hlavičku Retry-After.

API využívá systém rezervace při odeslání, zaúčtování při úspěchu a vrácení kreditů při selhání. Stránky s využitím v dashboardu zobrazují historii API kreditů, protokoly úloh a časové statistiky využití.