Seedance API

Rajapinnan avulla voit lähettää Seedance 2.5- ja Seedance 2.0 -videonluontitehtäviä ohjelmallisesti. Suositeltu malli on Seedance 2.5, joka tukee tekstistä videoksi -luontia, kuvasta videoksi -luontia (ensimmäisen ruudun tai ensimmäisen ja viimeisen ruudun perusteella) sekä monimuotoista viitteistä videoksi -luontia. Luonti tapahtuu asynkronisesti: luot tehtävän, saat heti tehtävätunnuksen (task ID) ja noudat valmiin videon joko kyselemällä tehtävän tilaa päätepisteestä tai vastaanottamalla webhook-ilmoituksen.

Luo API-avain hallintapaneelissa ja lähetä se jokaisen pyynnön mukana Bearer-tunnisteena (token). Koko avain näytetään vain kerran sen luonnin yhteydessä.

Authorization: Bearer sk_live_xxxxxxxx

Lähetä ensin tehtävä. Kun tehtävä on vastaanotettu, valitse toinen tuloksen toimitustavoista: kysy tehtävän tilaa päätepisteestä tai vastaanota lopullinen tulos webhookin kautta.

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

Luo videotehtävä tekemällä POST-pyyntö osoitteeseen /v1/videos/generations. Pyynnön runko (body) sisältää päätason model-kentän, valinnaisen callback_url-osoitteen sekä input-objektin, joka sisältää prompt-syötteen ja luontiasetukset.

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 määrittää, mitä mediatyyppejä pyynnössä hyväksytään ja miten malli tulkitsee niitä.

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

Parametrien nimet, enum-arvot, päätepisteiden polut ja esimerkit ovat osa API-sopimusta. Alla olevat kuvaukset selittävät kunkin kentän toiminnan.

Tämä on onnistunut vastaus POST /v1/videos/generations -pyyntöön. Se tarkoittaa, että tehtävä on vastaanotettu ja saldot on varattu. Käytä palautettua taskId-tunnusta kyselyyn GET /v1/tasks/:id tai yhdistääksesi sen valmistumis- tai virheilmoituksen callback-kutsuun.

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

Hae tehtävän nykyinen tila osoitteesta GET /v1/tasks/:id. Tee kyselyjä enintään kerran 10 sekunnissa. Tuotantojärjestelmissä suositellaan webhookien käyttöä.

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

Kun callback_url on määritetty, Seedance kutsuu päätepistettäsi tehtävän valmistuessa tai epäonnistuessa ja lähettää lopullisen tuloksen JSON-muodossa. Jos päätepisteesi palauttaa muun kuin 2xx-vastauksen tai ei vastaa 15 sekunnin kuluessa, lähetystä yritetään uudelleen enintään 5 kertaa. Uudelleenyritykset käyttävät samaa task id -tunnusta, joten poista kaksoiskappaleet tunnuksen perusteella. Palauta 200-vastaus heti, kun olet tallentanut callback-tiedot onnistuneesti.

{
  "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 ja GET /v1/tasks/:id palauttavat tämän virherakenteen, kun itse API-pyyntö epäonnistuu esimerkiksi virheellisten parametrien, virheellisen API-avaimen, riittämättömän saldon, käyttörajojen ylittymisen tai puuttuvan tehtävän vuoksi. Jotkin virheet sisältävät lisäkenttiä, kuten required, available tai retry_after tilanteesta riippuen.

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

Käyttörajat sovelletaan API-avainkohtaisesti liukuvalla aikaikkunalla. Videon luontipyynnöissä oletusraja on 100 pyyntöä minuutissa; tilakyselyissä rajat ovat joustavammat. HTTP 429 -vastaukset sisältävät Retry-After-otsakkeen.

API käyttää mallia, jossa saldo varataan lähetettäessä, veloitetaan onnistuessa ja palautetaan virhetilanteessa. Hallintapaneelin käyttösivuilta näet API-saldohistorian, tehtävälokit sekä ajanjaksoittaiset käyttötilastot.