Sviluppa con l'API di Seevio

Scegli un modello

Ogni riferimento del modello include i parametri completi, i prezzi e gli esempi. Puoi completare l'integrazione direttamente dalla pagina del singolo modello.

Autenticazione

Crea una chiave API nella dashboard. La chiave completa viene mostrata una sola volta. Conservala sul tuo server e inviala come token Bearer in ogni richiesta.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Imposta la variabile d'ambiente SEEVIO_API_KEY prima di eseguire questi esempi. Gli esempi in JavaScript vengono eseguiti sul server con Node.js; gli esempi in Python utilizzano la libreria requests.

Avvio rapido

Questo esempio genera un video da 5 secondi a 720p con Seedance 2.5. Apri la documentazione di un modello per visualizzare tutte le modalità di generazione e i limiti dei parametri.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

Esempio di risposta alla creazione del task

Una volta accettata la richiesta precedente, l'API restituisce questa risposta JSON. taskId è l'identificativo del task da utilizzare per le successive verifiche sullo stato; credits indica il numero di crediti riservati a questo task. Questa risposta conferma la corretta creazione del task, non che il video sia pronto. Sarà necessario monitorare periodicamente lo stato del task o utilizzare un Webhook per ricevere il video finale.

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 100
}

Interroga un task

Sostituisci l'ID di esempio con il taskId restituito alla creazione. Le query restituiscono solo i task associati all'utente della chiave API; ID non accessibili o inesistenti restituiscono HTTP 404.

Come punto di partenza, effettua un polling ogni 10–20 secondi, rallenta le richieste in caso di HTTP 429 e interrompi quando lo stato diventa completed o failed. Per gli ambienti di produzione, consigliamo l'uso dei webhook. Ogni esempio di codice seguente esegue una singola query.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

Task completato: risposta alla query con i risultati video

Quando la query restituisce status=completed, la generazione del video è terminata. Puoi trovare gli URL del video in data.results; assicurati di scaricarli prima della data indicata in data.video_expires_at. Lo stato billing_status=charged indica che i crediti prenotati sono stati effettivamente addebitati.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "completed",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

Task fallito: risposta alla query con dettagli sul fallimento e sulla fatturazione

Se la query restituisce status=failed, significa che la generazione non è andata a buon fine. Consulta failed_reason per conoscerne il motivo e billing_status per l'esito del rimborso. In questo esempio, lo stato refunded indica che i crediti sono stati riaccreditati. La voce credits mostra la quota inizialmente prenotata e la risposta non include la chiave data.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "failed",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

Webhook

Per le integrazioni in produzione, fornisci un callback_url alla creazione del task. Ogni riferimento del modello include i payload di callback e un esempio di ricevitore.

Imposta callback_url nella richiesta di creazione per ricevere una richiesta POST JSON al completamento o al fallimento del task. Restituisci una risposta 2xx entro 15 secondi. Gli invii non riusciti verranno riprovati; gestisci le notifiche duplicate in modo idempotente tramite l'ID del task.

L'endpoint di callback deve accettare richieste POST con un corpo in formato JSON (Content-Type: application/json).

Crea un task con callback

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

I payload dei webhook differiscono dalle risposte alle query sui task: omettono billing_status e credits; i dettagli sugli errori si trovano all'interno di data.failed_reason e data.credits_refunded. Il valore created_at del webhook indica il timestamp dell'evento in formato Unix (secondi).

Attività completata: payload di callback riuscito

In caso di generazione riuscita, la callback conterrà lo stato status=completed. Utilizza id per identificare l'attività e data.results per recuperare gli URL dei video. Assicurati di scaricare e salvare i risultati prima della scadenza indicata in data.video_expires_at.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "completed",
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

Attività non riuscita: payload di callback fallito

In caso di errore durante la generazione, la callback conterrà lo stato status=failed. Utilizza id per identificare l'attività, data.failed_reason per conoscere il motivo del fallimento e data.credits_refunded per verificare il numero di crediti riaccreditati.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "failed",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 100
  }
}

Esempio di ricevitore

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrls = callbackData.data.results;
    // Save the video URLs and mark this task as completed in your application.
    console.log(callbackData.id, videoUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData.data;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

Questo esempio in Next.js legge il corpo JSON della callback e gestisce direttamente le attività completate e fallite. Ti consigliamo di aggiungere logiche di persistenza e deduplicazione dei task-ID per la tua applicazione, e di accodare i processi più lenti prima di confermare la callback.

Errori

Gli errori HTTP contengono un oggetto error con code e message. Un task accettato correttamente può comunque fallire in una fase successiva; interroga lo stato del task o gestisci la chiamata di callback per l'errore.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}