API per sviluppatori

Costruisci con SeeDanceE2.ai.

Basata sul modello sottostante Seedance 2.0, la nostra API unifica e incapsula le capacità dei provider a monte e le espone come API pubblica standardizzata.

model: promodel: fastmodel: mini
Contratto API stabile

Integra una sola volta `pro`, `fast` e `mini`, mentre manteniamo i cambiamenti dei provider a monte dietro lo stesso contratto pubblico.

Workflow testo e immagine

Esegui la generazione video da prompt o immagini tramite un'unica superficie API, senza esporre ai clienti differenze specifiche dei provider a monte.

Job asincroni, polling, webhook

Invia una richiesta di generazione, controlla lo stato del job o ricevi un webhook quando il video è pronto con una risposta SeeDanceE2 pulita.

Contratto pubblico

Una sola superficie API per la generazione video

L'API pubblica nasconde i provider a monte. Gli sviluppatori integrano tre nomi di modello pubblici, un solo schema di autenticazione e un solo ciclo di vita delle attività asincrone.

Autenticazione

Chiavi API bearer

Invia `Authorization: Bearer sk_seedancee2_live_xxxxx` con ogni richiesta.

Ciclo di vita delle attività

Invio, polling, webhook

Crea un'attività di generazione asincrona, interroga per ID o ricevi callback di completamento.

Utilizzo e crediti

Riservati e addebitati

Le risposte espongono crediti riservati, addebitati e rimborsati per mantenere la fatturazione verificabile.

Nomi dei modelli pubblici

Usa solo `pro`, `fast` e `mini`

pro

Qualità di produzione

Per clip destinate ai clienti e lavori di produzione standard.

480p, 720p, 1080p
fast

Iterazione più rapida

Per flussi di anteprima ed esperimenti ripetuti sui prompt.

480p, 720p
mini

Test a costi contenuti

Per bozze leggere e generazione con budget ridotto.

480p, 720p
Domande sull'API

Domande frequenti

Come autentico le richieste all'API di generazione video?

Crea una chiave API nel tuo workspace e inviala come token bearer: Authorization: Bearer sk_seedancee2_live_xxxxx in ogni richiesta.

L'API è sincrona o asincrona?

La generazione è asincrona. Invii un'attività, ricevi un ID attività, poi interroghi l'endpoint di stato o registri un webhook per essere avvisato quando il video è pronto.

Quali nomi di modello posso richiedere?

Solo i livelli pubblici pro, fast e mini. La piattaforma instrada ogni richiesta verso il miglior modello video sottostante disponibile, così la tua integrazione non si rompe quando cambiano i provider.

Come funziona la fatturazione dell'API?

L'uso dell'API attinge allo stesso saldo crediti dell'app web. Le risposte espongono credits_reserved, credits_charged e credits_refunded così ogni chiamata resta verificabile.

L'API supporta anche image-to-video oltre a text-to-video?

Sì. Invia un prompt testuale per il text-to-video, oppure allega l'URL di un'immagine di riferimento per l'image-to-video; la composizione dell'immagine viene preservata e viene generato solo il movimento descritto.

API video pubblica di SeeDanceE2

SeeDanceE2 espone un'API pubblica stabile per la generazione video. Le integrazioni devono usare solo i nomi di modello pubblici pro, fast e mini; i dettagli dei provider a monte restano nascosti dietro il contratto SeeDanceE2.

URL di base

https://api.SeeDanceE2.ai

Avvio rapido

  1. Richiedi una chiave API al team SeeDanceE2.
  2. Crea un'attività di generazione video.
  3. Interroga l'attività o ricevi un webhook al completamento.

Esempio minimo con curl:

curl -X POST "https://api.SeeDanceE2.ai/v1/videos/generations" \
  -H "Authorization: Bearer sk_seedancee2_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mini",
    "input": {
      "prompt": "A cinematic drone shot of waves breaking against black volcanic rocks",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    },
    "metadata": {
      "customer_job_id": "job_123"
    }
  }'

Esempio minimo in JavaScript:

const response = await fetch("https://api.SeeDanceE2.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_seedancee2_live_xxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "mini",
    input: {
      prompt: "A cinematic drone shot of waves breaking against black volcanic rocks",
      duration: 5,
      resolution: "720p",
      aspect_ratio: "16:9",
    },
    metadata: {
      customer_job_id: "job_123",
    },
  }),
});

const result = await response.json();
console.log(result);

Esempio minimo in Python:

import requests

response = requests.post(
    "https://api.SeeDanceE2.ai/v1/videos/generations",
    headers={
        "Authorization": "Bearer sk_seedancee2_live_xxxxx",
        "Content-Type": "application/json",
    },
    json={
        "model": "mini",
        "input": {
            "prompt": "A cinematic drone shot of waves breaking against black volcanic rocks",
            "duration": 5,
            "resolution": "720p",
            "aspect_ratio": "16:9",
        },
        "metadata": {
            "customer_job_id": "job_123",
        },
    },
    timeout=60,
)

print(response.json())

Autenticazione

Tutte le richieste usano l'autenticazione con token bearer.

Authorization: Bearer sk_seedancee2_live_xxxxx
Content-Type: application/json

Puoi inviare la chiave anche tramite x-api-key, ma Authorization: Bearer ... è la modalità consigliata.

Chiavi API e accesso ai modelli

  • La tua chiave API SeeDanceE2 viene emessa dal team SeeDanceE2 o dal tuo profilo.
  • La stessa chiave API SeeDanceE2 funziona con tutti i modelli pubblici: pro, fast e mini.
  • Non servono chiavi API separate per Mini, Fast o Pro.
  • Le credenziali dei provider a monte sono gestite da SeeDanceE2 e non sono mai richieste nelle richieste del cliente.

Se hai già una chiave API SeeDanceE2 funzionante, cambiare modello richiede solo la modifica del campo model nella richiesta. Esempio:

{
  "model": "mini"
}

diventa:

{
  "model": "fast"
}

oppure:

{
  "model": "pro"
}

Modelli pubblici

Questi sono i nomi di modello pubblici che la tua integrazione deve usare.

ModelloPosizionamentoDurataRisoluzione
proGenerazione di produzione in qualità standard4-15 s480p, 720p, 1080p
fastIterazione rapida e flussi di anteprima4-15 s480p, 720p
miniGenerazione a costi contenuti4-15 s480p, 720p

Le nuove integrazioni devono usare pro, fast e mini.

Proporzioni supportate:

16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive

Crediti

I crediti dell'API pubblica seguono le stesse regole di addebito visibili nel prodotto SeeDanceE2.

Formula:

credits = duration_seconds * per_second_rate * number_of_outputs

Immagini, video e audio di riferimento al momento non comportano supplementi aggiuntivi per il cliente. I valori di crediti riservati e addebitati nella risposta API sono la fonte di verità per ogni attività.

Tariffe al secondo attualmente allineate alle regole di fatturazione del prodotto SeeDanceE2:

Modello480p720p1080p
pro10 crediti/s20 crediti/s50 crediti/s
fast8 crediti/s16 crediti/sNon supportato
mini5 crediti/s10 crediti/sNon supportato

Esempi:

ScenarioCrediti
mini, 5 s, 720p50
pro, 4 s, 480p40
fast, 10 s, 720p160
pro, 5 s, 720p, 2 immagini di riferimento100

Se un'attività non riesce ed è idonea al rimborso, il payload di stato restituito mostra i crediti rimborsati.

Ciclo di vita delle attività

Stati dell'attività restituiti dall'API pubblica:

StatoSignificato
pendingAccettata e in attesa di avvio
processingIn esecuzione
completedCompletata con successo
failedTerminata senza un output utilizzabile

Creare un'attività video

POST /v1/videos/generations

Campi di primo livello della richiesta:

CampoTipoObbligatorioDescrizione
modelstringSìNome del modello pubblico: pro, fast o mini
inputobjectSìParametri di generazione
callback_urlstringNoURL webhook pubblico per callback di completamento o errore
metadataobjectNoMetadati definiti dal cliente, restituiti nelle risposte di polling e webhook

Campi di input:

CampoTipoObbligatorioDescrizione
promptstringSìPrompt testuale
generation_typestringNoomni_reference o first_and_last_frames; predefinito omni_reference
image_urlsstring[]NoURL delle immagini di riferimento
video_urlstringNoURL di un singolo video di riferimento
video_urlsstring[]NoURL dei video di riferimento. Non inviare insieme a video_url
audio_urlsstring[]NoURL degli audio di riferimento
start_image_urlstringNoImmagine del primo fotogramma per first_and_last_frames
end_image_urlstringNoImmagine dell'ultimo fotogramma per first_and_last_frames
durationintegerNoDurata dell'output in secondi, 4-15; predefinito 5
resolutionstringNo480p, 720p o 1080p; le risoluzioni disponibili dipendono dal modello scelto
aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9 o adaptive
generate_audiobooleanNoGenera audio sincronizzato quando supportato
watermarkbooleanNoRichiede un output con filigrana
seedintegerNoSeed deterministico
return_last_framebooleanNoInclude l'immagine dell'ultimo fotogramma nel payload di output

Esempio completo:

curl -X POST "https://api.SeeDanceE2.ai/v1/videos/generations" \
  -H "Authorization: Bearer sk_seedancee2_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pro",
    "callback_url": "https://example.com/webhooks/seedancee2",
    "input": {
      "prompt": "A cinematic tracking shot through a rain-soaked neon market at night",
      "image_urls": [
        "https://example-cdn.com/reference-1.png",
        "https://example-cdn.com/reference-2.png"
      ],
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true,
      "return_last_frame": true
    },
    "metadata": {
      "customer_job_id": "job_123",
      "campaign": "launch_week"
    }
  }'

Risposta di successo:

{
  "data": {
    "id": "vid_01jz8b7q4x8k2p9w3m5c6n7r8s",
    "status": "pending",
    "model": "pro",
    "credits_reserved": 100,
    "created_at": "2026-06-29T10:00:00.000Z"
  }
}

Recuperare un'attività video

GET /v1/videos/generations/{id}

Esempio di polling:

const response = await fetch(
  "https://api.SeeDanceE2.ai/v1/videos/generations/vid_01jz8b7q4x8k2p9w3m5c6n7r8s",
  {
    headers: {
      Authorization: "Bearer sk_seedancee2_live_xxxxx",
    },
  }
);

const result = await response.json();
console.log(result);

Risposta durante l'elaborazione:

{
  "data": {
    "id": "vid_01jz8b7q4x8k2p9w3m5c6n7r8s",
    "status": "processing",
    "model": "pro",
    "created_at": "2026-06-29T10:00:00.000Z",
    "metadata": {
      "customer_job_id": "job_123",
      "campaign": "launch_week"
    }
  }
}

Risposta al completamento:

{
  "data": {
    "id": "vid_01jz8b7q4x8k2p9w3m5c6n7r8s",
    "status": "completed",
    "model": "pro",
    "created_at": "2026-06-29T10:00:00.000Z",
    "completed_at": "2026-06-29T10:06:20.000Z",
    "credits_charged": 100,
    "output": {
      "video_url": "https://media.SeeDanceE2.ai/videos/2026/06/29/vid_01jz8b7q4x8k2p9w3m5c6n7r8s.mp4",
      "thumbnail_url": "https://media.SeeDanceE2.ai/video-posters/2026/06/29/vid_01jz8b7q4x8k2p9w3m5c6n7r8s.jpg",
      "last_frame_url": "https://media.SeeDanceE2.ai/video-posters/2026/06/29/vid_01jz8b7q4x8k2p9w3m5c6n7r8s.jpg"
    },
    "metadata": {
      "customer_job_id": "job_123",
      "campaign": "launch_week"
    }
  }
}

Risposta di errore:

{
  "data": {
    "id": "vid_01jz8b7q4x8k2p9w3m5c6n7r8s",
    "status": "failed",
    "model": "pro",
    "created_at": "2026-06-29T10:00:00.000Z",
    "credits_charged": 0,
    "credits_refunded": 100,
    "error": {
      "code": "generation_failed",
      "message": "The video could not be generated. Please try again with a different prompt.",
      "type": "generation_error"
    },
    "metadata": {
      "customer_job_id": "job_123",
      "campaign": "launch_week"
    }
  }
}

Elencare le attività video

GET /v1/videos/generations

Parametri di query supportati:

CampoTipoDescrizione
statusstringFiltra per pending, processing, completed o failed
limitintegerNumero massimo di risultati. Predefinito 20, massimo 100

Esempio:

curl "https://api.SeeDanceE2.ai/v1/videos/generations?status=completed&limit=10" \
  -H "Authorization: Bearer sk_seedancee2_live_xxxxx"

Elencare i modelli

GET /v1/models

Esempio di risposta:

{
  "data": [
    {
      "id": "pro",
      "status": "active",
      "resolutions": ["480p", "720p", "1080p"],
      "duration": {
        "min": 4,
        "max": 15
      }
    }
  ]
}

Riepilogo utilizzo

GET /v1/usage

Parametri di query supportati:

CampoTipoDescrizione
startstringFiltro facoltativo sulla data e ora di inizio in formato ISO 8601
endstringFiltro facoltativo sulla data e ora di fine in formato ISO 8601
limitintegerNumero massimo di righe della cronologia giornaliera. Predefinito 30, massimo 365

Esempio:

curl "https://api.SeeDanceE2.ai/v1/usage?start=2026-07-01T00:00:00.000Z&end=2026-07-31T23:59:59.999Z&limit=7" \
  -H "Authorization: Bearer sk_seedancee2_live_xxxxx"

Esempio di risposta:

{
  "data": {
    "range": {
      "start": "2026-07-01T00:00:00.000Z",
      "end": "2026-07-31T23:59:59.999Z"
    },
    "summary": {
      "total_jobs": 12,
      "pending_jobs": 1,
      "processing_jobs": 2,
      "completed_jobs": 8,
      "failed_jobs": 1,
      "credits_charged": 280,
      "credits_refunded": 40,
      "net_credits": 240
    },
    "by_model": [
      {
        "model": "mini",
        "total_jobs": 7,
        "pending_jobs": 0,
        "processing_jobs": 1,
        "completed_jobs": 5,
        "failed_jobs": 1,
        "credits_charged": 120,
        "credits_refunded": 20,
        "net_credits": 100
      },
      {
        "model": "pro",
        "total_jobs": 5,
        "pending_jobs": 1,
        "processing_jobs": 1,
        "completed_jobs": 3,
        "failed_jobs": 0,
        "credits_charged": 160,
        "credits_refunded": 20,
        "net_credits": 140
      }
    ],
    "timeline": [
      {
        "date": "2026-07-01",
        "total_jobs": 4,
        "pending_jobs": 0,
        "processing_jobs": 1,
        "completed_jobs": 3,
        "failed_jobs": 0,
        "credits_charged": 100,
        "credits_refunded": 0,
        "net_credits": 100
      }
    ]
  }
}

Webhook

Se viene fornito callback_url, SeeDanceE2 invia una richiesta POST quando l'attività raggiunge completed o failed.

Header consigliati da verificare:

X-Seedancee2-Event: video.generation.completed
X-Seedancee2-Signature: t=1770000000,v1=...

Se la firma dei webhook è attiva sul tuo account, il corpo viene firmato così:

payload_to_sign = "{timestamp}.{raw_json_body}"
signature = hex(hmac_sha256(webhook_secret, payload_to_sign))

Payload del webhook al completamento:

{
  "data": {
    "id": "vid_01jz8b7q4x8k2p9w3m5c6n7r8s",
    "status": "completed",
    "model": "pro",
    "created_at": "2026-06-29T10:00:00.000Z",
    "completed_at": "2026-06-29T10:06:20.000Z",
    "credits_charged": 100,
    "output": {
      "video_url": "https://media.SeeDanceE2.ai/videos/2026/06/29/vid_01jz8b7q4x8k2p9w3m5c6n7r8s.mp4",
      "thumbnail_url": "https://media.SeeDanceE2.ai/video-posters/2026/06/29/vid_01jz8b7q4x8k2p9w3m5c6n7r8s.jpg"
    },
    "metadata": {
      "customer_job_id": "job_123",
      "campaign": "launch_week"
    }
  }
}

Payload del webhook in caso di errore:

{
  "data": {
    "id": "vid_01jz8b7q4x8k2p9w3m5c6n7r8s",
    "status": "failed",
    "model": "pro",
    "created_at": "2026-06-29T10:00:00.000Z",
    "credits_charged": 0,
    "credits_refunded": 100,
    "error": {
      "code": "generation_failed",
      "message": "The video could not be generated. Please try again with a different prompt.",
      "type": "generation_error"
    },
    "metadata": {
      "customer_job_id": "job_123",
      "campaign": "launch_week"
    }
  }
}

Linee guida sugli input

Immagini:

RequisitoValore
FormatiJPEG, PNG, WebP, BMP, TIFF, GIF
QuantitàFino a 9 immagini di riferimento
first_and_last_framesEsattamente 2 immagini

Video:

RequisitoValore
video_url1
video_urlsFino a 3

Audio:

RequisitoValore
audio_urlsFino a 3

Errori

Formato dell'errore:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

Codici di errore pubblici attuali:

Stato HTTPCodiceTipoDescrizione
400invalid_requestinvalid_request_errorParametri mancanti o non validi
401invalid_api_keyauthentication_errorChiave API assente, non valida o disattivata
402insufficient_creditsbilling_errorSaldo crediti insufficiente
404model_not_foundinvalid_request_errorIl modello non esiste o è inattivo
404task_not_foundinvalid_request_errorL'ID attività non esiste
500internal_errorapi_errorErrore imprevisto del server

Note di integrazione

  • Usa solo nomi di modello pubblici come pro, fast e mini.
  • Non costruire logica basata su nomi di provider interni, ID attività interni o host media interni.
  • Salva i tuoi metadata per collegare callback e risultati di polling ai record aziendali interni.
  • In produzione preferisci i webhook per il completamento e mantieni il polling come fallback.