Seedance API

API umożliwia programowe zlecanie zadań generowania wideo przy użyciu modeli Seedance 2.5 oraz Seedance 2.0. Seedance 2.5 to zalecany model, który obsługuje generowanie z tekstu na wideo, z obrazu na wideo (na podstawie pierwszej ramki lub pierwszej i ostatniej) oraz z multimodalnych referencji na wideo. Generowanie odbywa się asynchronicznie: po utworzeniu zadania natychmiast otrzymujesz jego identyfikator (ID), a gotowe wideo odbierasz poprzez odpytywanie punktu końcowego zadania lub za pomocą webhooka.

Utwórz klucz API w panelu i przesyłaj go jako token Bearer w nagłówku każdego żądania. Pełny klucz jest wyświetlany tylko raz, bezpośrednio po jego utworzeniu.

Authorization: Bearer sk_live_xxxxxxxx

Najpierw prześlij zadanie. Gdy zostanie zaakceptowane, wybierz preferowany sposób odbioru wyniku: możesz odpytywać punkt końcowy zadania lub odebrać ostateczny rezultat za pomocą webhooka.

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 });
}

Utwórz zadanie wideo, wykonując żądanie POST /v1/videos/generations. Treść żądania zawiera główny parametr model, opcjonalny callback_url oraz obiekt input z opisem (prompt) i ustawieniami generowania.

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 określa, jakie pliki wejściowe są akceptowane i jak model ma je zinterpretować.

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"
    }
  }'

Nazwy parametrów, wartości typów wyliczeniowych (enum), ścieżki punktów końcowych i przykłady stanowią stałą część specyfikacji API. Poniższe opisy wyjaśniają działanie poszczególnych pól.

To jest poprawna odpowiedź zwrotna z żądania POST /v1/videos/generations. Oznacza ona, że zadanie zostało przyjęte do realizacji, a kredyty zostały zarezerwowane. Użyj zwróconego taskId do odpytywania GET /v1/tasks/:id lub do powiązania go z nadesłanym webhookiem.

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

Użyj GET /v1/tasks/:id, aby pobrać aktualny stan zadania. Nie odpytuj częściej niż raz na 10 sekund. W systemach produkcyjnych zaleca się stosowanie webhooków.

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"
}

Jeśli parametr callback_url jest podany, Seedance wyśle żądanie na Twój punkt końcowy po zakończeniu zadania (sukcesem lub błędem), przesyłając dane JSON z ostatecznym rezultatem. Jeśli Twój serwer zwróci kod inny niż 2xx lub nie odpowie w ciągu 15 sekund, próba zostanie ponowiona maksymalnie 5 razy. Ponowne próby korzystają z tego samego identyfikatora zadania (task id), co pozwala na eliminację duplikatów. Zwróć odpowiedź z kodem 200 od razu po bezpiecznym zapisaniu danych z powiadomienia.

{
  "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 });
}

Metody POST /v1/videos/generations i GET /v1/tasks/:id zwracają poniższą strukturę błędu, gdy samo żądanie do API zakończy się niepowodzeniem (np. nieprawidłowe parametry, błędny klucz API, niewystarczająca liczba kredytów, przekroczenie limitów lub nieznalezione zadanie). Niektóre błędy mogą zawierać dodatkowe pola, takie jak required, available lub retry_after.

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

Limity częstotliwości żądań są naliczane dla każdego klucza API w oparciu o ruchome okno czasowe. Limit dla generowania wynosi domyślnie 100 żądań na minutę; zapytania o status zadania podlegają łagodniejszym limitom. Odpowiedzi HTTP 429 zawierają nagłówek Retry-After.

API działa w modelu: rezerwacja przy zgłoszeniu zadania, pobranie opłaty przy sukcesie i zwrot środków przy błędzie. W zakładkach rozliczeń w panelu znajdziesz historię zużycia kredytów API, dzienniki zadań oraz statystyki użycia w czasie.