Riferimento API

Video

Modelli su questo endpoint (13)

doubao-seedance-2.5 kling-v3 veo3.1-fast gemini-omni-1.1-flash gemini-omni-1.1-flash-ext grok-imagine-1.5-video kling-v2-6-motion-control kling-v3-motion-control+9+5

Provalo nel Workbench

POST/v1/videos

GET/v1/videos/{task_id}

GET/v1/videos/{task_id}/content

Generazione video asincrona (Seedance, Kling, Veo, Wan, Grok Imagine …). /v1/videos accetta input da testo a video e da immagine a video in un'unica richiesta in formato OpenAI. Restituisce un task_id da interrogare — oppure registra un webhook al momento dell'invio.

#Parametri della richiesta

modelstringobbligatorio
Un ID di modello video dalla pagina dei modelli, per esempio doubao-seedance-2.5.
promptstringobbligatorio
Descrizione della scena; per image2video guida il movimento.
imagestringfacoltativo
Solo image2video: immagine del primo fotogramma come URL o base64.
imagesarrayfacoltativo
Fotogrammi di riferimento per i fornitori che accettano più immagini in un task.
durationnumberfacoltativo
Durata della clip in secondi — una dimensione della fascia di prezzo; valori supportati nella scheda del modello.
secondsnumberfacoltativo
Alias usato da alcune famiglie di modelli per la durata della clip; preferisci il campo duration.
resolutionstringfacoltativo
Fascia di risoluzione dell'output, come 720p o 1080p, quando il modello la espone.
sizestringfacoltativo
Selettore di proporzioni o dimensioni per le famiglie di modelli che usano dimensioni nel formato larghezza x altezza.
webhook_urlstringfacoltativo
URL HTTPS chiamato quando il task raggiunge uno stato finale — vedi la guida ai video per il contratto della callback.
webhook_secretstringfacoltativo
Se impostato, le consegne includono X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret)).

Parametri del fornitore inoltrati

Le famiglie di modelli accettano parametri extra del fornitore (aspect_ratio, cfg_scale, negative_prompt …) che vengono inoltrati invariati — la scheda del modello li documenta; i campi sconosciuti vengono rifiutati upstream, non dal gateway.

I task falliti vengono rimborsati automaticamente

I task video vengono pre-addebitati all'invio e rimborsati per intero se il task termina con failed — il registro contabile annota il rimborso con un collegamento all'addebito originale.

#Annulla un task in esecuzione

DELETE/v1/videos/:task_id

Interrompe un task che non ha raggiunto uno stato finale. In caso di successo la quota riservata viene rimborsata, il task viene registrato come failed con il motivo "cancelled by user" e qualsiasi webhook registrato scatta come task.failed.

La maggior parte dei provider non può annullare

L'annullamento viene inoltrato al provider upstream, e solo alcuni lo espongono. Tutti gli altri rispondono 501 task_cancel_not_supported. Tratta l'annullamento come best-effort nella tua UI: continua il polling e non promettere un rimborso all'utente prima che la chiamata restituisca 200.

curl -X DELETE https://www.aisplice.store/v1/videos/task_xxx \
  -H "Authorization: Bearer sk-YOUR_KEY"

cancelled.json

{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "status": "cancelled"
}

Nota che "cancelled" compare solo in questa risposta. Un polling successivo riporta il task come failed, perché è lo stato in cui è stato spostato.

404 task_not_existId del task sconosciuto, oppure appartiene a un altro account.
409 task_not_cancellableIl task è già terminato — non c'è nulla da fermare.
501 task_cancel_not_supportedQuesto provider non espone un'API di annullamento.

Tabella completa dei codici di errore →

#Remix di un video esistente

POST/v1/videos/:video_id/remix

Rigenera un video finito con un nuovo prompt, sui modelli che lo supportano. Invia solo prompt: modello, durata, risoluzione e fattori di prezzo sono tutti ereditati dal task originale e la richiesta resta vincolata al canale che l'ha prodotto.

curl https://www.aisplice.store/v1/videos/task_xxx/remix \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: remix-of-task_xxx" \
  -d '{"prompt": "Same shot, at night"}'

remix.json

{
  "task_id": "task_yyy",
  "status": "queued",
  "remixed_from_video_id": "task_xxx"
}

Un remix è un nuovo task fatturabile

Costa quanto l'originale, segue lo stesso ciclo di vita e restituisce un proprio task_id. Interroga il nuovo id — l'originale resta intatto.

400 invalid_requestprompt è obbligatorio in un remix.
400 task_not_existL'id del video di origine è sconosciuto o appartiene a un altro account.
400 task_channel_disableIl canale che ha prodotto il video originale non è più attivo.

Tabella completa dei codici di errore →

#Errori correlati

404 not_foundPercorso sconosciuto, nome del modello sconosciuto o un task_id scaduto o di un altro account.
422 unprocessable_entityIl fornitore ha rifiutato i valori dei parametri inoltrati dal gateway (per esempio dimensione o durata non supportate).
401Bearer token non valido o mancante. Su questo percorso non c'è error.code — basati sullo stato.
402 insufficient_user_quotaIl saldo del portafoglio non copre la stima pre-riservata.
429Limitazione per chiave. Corpo vuoto; attendi Retry-After. Un 429 che contiene insufficient_user_quota indica invece un limite di spesa giornaliero.
503 model_not_foundModello sconosciuto, oppure nessun canale funzionante lo serve al momento.

Tabella completa dei codici di errore →

#Esempio di richiesta

# submit
curl https://www.aisplice.store/v1/videos \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "doubao-seedance-2.5", "prompt": "A drone shot of a lighthouse at dawn"}'

# poll every 5s
curl https://www.aisplice.store/v1/videos/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"

# download when completed
curl -L https://www.aisplice.store/v1/videos/$TASK_ID/content -o out.mp4 -H "Authorization: Bearer sk-YOUR_KEY"

#Risposta

response.json

// POST — submit accepted
{"task_id": "task_xxx", "status": "queued"}

// GET /v1/videos/{task_id}
{
  "task_id": "task_xxx",
  "status": "in_progress",      // queued | in_progress | completed | failed
  "progress": "45%"
}

// terminal state
{
  "task_id": "task_xxx",
  "status": "completed",
  "metadata": {"url": "https://…"}
}

Non hai ancora risolto?

Inviaci l'ID richiesta o il messaggio di errore e verificheremo.

PrecedenteImmagini: task asincroni SuccessivoMusica