Seedance-API

Mit der API können Sie Videogenerierungstasks für Seedance 2.5 und Seedance 2.0 programmatisch starten. Seedance 2.5 ist das empfohlene Modell und unterstützt Text-to-Video, Image-to-Video (mit erstem Frame oder erstem und letztem Frame) sowie multimodales Reference-to-Video. Die Generierung erfolgt asynchron: Sie erstellen einen Task, erhalten sofort eine Task-ID und rufen das fertige Video entweder per Polling über den Task-Endpunkt ab oder lassen es sich per Webhook senden.

Erstellen Sie im Dashboard einen API-Key und senden Sie diesen bei jeder Anfrage als Bearer-Token mit. Der vollständige Key wird Ihnen nur ein einziges Mal direkt nach der Erstellung angezeigt.

Authorization: Bearer sk_live_xxxxxxxx

Senden Sie zuerst einen Task ab. Sobald dieser akzeptiert wurde, wählen Sie eine Methode zur Bereitstellung des Ergebnisses: Fragen Sie den Task-Endpunkt ab (Polling) oder empfangen Sie das finale Ergebnis direkt über einen 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 });
}

Erstellen Sie einen Videotask mit POST /v1/videos/generations. Der Request-Body enthält das primäre model, eine optionale callback_url sowie ein input-Objekt mit dem Prompt und den Generierungseinstellungen.

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

generation_type steuert, welche Medien-Inputs akzeptiert und wie diese vom Modell interpretiert werden.

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

Parameternamen, Enum-Werte, Endpunkt-Pfade und Beispiele sind fester Bestandteil des API-Vertrags. Die folgenden Beschreibungen erläutern die Funktionsweise der einzelnen Felder.

Dies ist die Erfolgsantwort von POST /v1/videos/generations. Sie bestätigt, dass der Task akzeptiert und das Guthaben reserviert wurde. Nutzen Sie die zurückgegebene taskId für Polling über GET /v1/tasks/:id oder zum Abgleich mit einem Webhook-Callback.

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

Nutzen Sie GET /v1/tasks/:id, um den aktuellen Task-Status abzurufen. Führen Sie Polling maximal alle 10 Sekunden durch. Für Produktionsumgebungen wird die Nutzung von Webhooks empfohlen.

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

Wenn eine callback_url angegeben ist, ruft Seedance Ihren Endpunkt auf, sobald der Task erfolgreich abgeschlossen wurde oder fehlgeschlagen ist, und sendet JSON-Daten mit dem finalen Ergebnis. Wenn Ihr Endpunkt keinen 2xx-Erfolgscode zurückgibt oder nicht innerhalb von 15 Sekunden antwortet, wird die Zustellung bis zu 5-mal wiederholt. Wiederholungsversuche nutzen dieselbe task id – führen Sie daher eine Duplikatsbereinigung anhand der ID durch. Senden Sie eine 200-Antwort zurück, sobald Sie die Callback-Daten sicher gespeichert haben.

{
  "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 und GET /v1/tasks/:id geben diese Fehlerstruktur zurück, wenn die API-Anfrage selbst fehlschlägt (z. B. bei ungültigen Parametern, falschem API-Key, unzureichendem Guthaben, Rate-Limiting oder wenn der Task nicht gefunden wurde). Einige Fehler enthalten je nach Kontext zusätzliche Felder wie required, available oder retry_after.

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

Rate Limits werden pro API-Key über ein gleitendes Zeitfenster (Sliding Window) angewendet. Die Videogenerierung ist standardmäßig auf 100 Anfragen pro Minute beschränkt; Statusabfragen sind großzügiger geregelt. HTTP-429-Antworten enthalten einen Retry-After-Header.

Die API nutzt das Prinzip: Reservierung beim Absenden, Abbuchung bei Erfolg und Rückerstattung bei Fehlern. Im Dashboard finden Sie den API-Guthabenverlauf, Task-Logs und zeitbasierte Nutzungsstatistiken.