Guida introduttiva

Scegli un modello e un endpoint nel Catalogo, quindi invia gli input richiesti dall’endpoint. Questo esempio avvia un Task Flux 2 da testo a immagine:

Una richiesta asincrona accettata restituisce 202 Accepted con un identificatore di Task:

Conserva id con il record della tua applicazione. È l’identificatore stabile utilizzato per il polling, il supporto e la riconciliazione dei callback.

I Media Input Field sono i campi della richiesta che contengono URL di contenuti multimediali: i campi di primo livello il cui nome termina con _url o _urls, come image_url o image_urls, l’url di ogni elemento di video_list e element_input_urls, element_input_video_urls ed element_input_audio_urls di ogni elemento di kling_elements. callback_url è un endpoint di consegna, non un Media Input Field. Ogni valore di un Media Input Field può essere un URL HTTPS pubblico o un data URI nel formato data:<mime>;base64,<data>, fino a 10 MB per data URI. RunAPI salva ogni data URI come File Upload temporaneo che scade dopo un’ora e usa quel caricamento per il Task. Un data URI che non può essere salvato restituisce 422 con il codice di errore invalid_media_input.

Gli endpoint di modifica GPT Image accettano solo URL HTTPS in source_image_urls. Per inviare un’immagine locale a questi endpoint, crea prima un File Upload e passa l’URL restituito.

Per file superiori a 10 MB, crea prima un File Upload con POST /api/v1/files e passa l’URL restituito. Un File Upload multipart o da URL accetta file fino a 50 MB. Anche gli URL dei File Upload scadono dopo un’ora, quindi crea un nuovo File Upload per ogni Task che inizia dopo tale intervallo.

Gli endpoint di creazione delle attività accettano un header facoltativo Idempotency-Key con un valore opaco fino a 512 caratteri. Genera un valore per ogni attività logica e conservalo con la richiesta fino a quando non sai se è stata accettata.

Se un timeout o un errore di connessione lascia il risultato sconosciuto, riprova la stessa identica richiesta di creazione del Task con la stessa chiave. RunAPI restituisce il Task originale invece di crearne e addebitarne uno nuovo. Il riutilizzo di una chiave con una richiesta di creazione di Task diversa restituisce 409 Conflict. Genera una nuova chiave per un Task intenzionalmente nuovo e non utilizzare X-Client-Request-Id come questa chiave.

Gli endpoint sincroni lenti di norma mantengono la connessione aperta e restituiscono la stessa risposta terminale di prima. Non sono necessarie modifiche al polling per le integrazioni esistenti.

Per un budget di connessione intenzionalmente più breve, invia Prefer: wait=N. Se il Task è ancora in esecuzione dopo quel budget esplicito, RunAPI restituisce 202 Accepted con lo stesso id del Task, un URL Location opaco per il recupero e Retry-After per il ritardo di query suggerito. Segui Location esattamente anziché costruire un URL di risultato. Un risultato Task completato conserva lo stato HTTP terminale, le intestazioni consentite, il tipo di contenuto e il corpo; decodifica response.body in base a response.content_type, che non è sempre JSON.

Aggiungi l’identificatore del Task allo stesso percorso dell’endpoint:

Continua finché status è processing. Usa un backoff limitato tra le richieste invece di eseguire il polling in modo continuo. Un Task diventa terminale quando il suo status è completed o failed.

Una risposta completed include l’id del Task, lo status terminale, i campi risultato specifici dell’endpoint e usage.cost come importo float USD per quel Task. Conserva il risultato necessario e interrompi il polling. Consulta il Riferimento API dell’endpoint per la forma esatta del risultato anziché presumere che ogni endpoint multimediale restituisca gli stessi campi.

Gli envelope Task di creazione, processing e failed omettono usage.

I Task che richiedono un conteggio finale basato sui contenuti multimediali rimangono in processing finché non viene registrato l’addebito definitivo. Il callback di completamento viene inviato solo dopo tale conteggio; il suo usage.cost coincide con quello delle successive query del Task. I dati contabili mancanti non vengono riportati come zero: il Task rimane in processing durante la loro riconciliazione. Un addebito pari a zero confermato viene restituito come usage.cost: 0.

Una risposta failed include l’id del Task, lo status terminale e un error redatto da RunAPI quando disponibile. Interrompi il polling, registra l’identificatore e l’errore, e riprova solo quando l’applicazione ha classificato il fallimento come transitorio. Un nuovo tentativo crea un nuovo identificatore di Task.

Aggiungi un callback_url HTTPS pubblico alla richiesta di creazione quando vuoi che RunAPI invii gli eventi di callback documentati per quell’endpoint:

Ogni corpo di callback corrisponde a un evento del ciclo di vita nel Riferimento API dell’endpoint. Un callback completed condivide usage.cost con la risposta di polling completed; i callback di creazione, processing e failed omettono usage. I callback terminali includono gli stessi campi di risultato delle risposte di polling terminali; alcuni endpoint inviano anche callback processing documentati. Restituisci rapidamente una risposta HTTP di successo e mantieni disponibile il polling per la riconciliazione quando la consegna è ritardata o il tuo gestore di callback non è disponibile.

Leggi Callback per creare un Callback Secret, verificare le firme e gestire i tentativi in modo sicuro.

Utilizzare POST /api/v1/vidu/image_to_video con model: "vidu-q4-image-to-video" e first_frame_image_url. Utilizzare POST /api/v1/vidu/reference_to_video con model: "vidu-q4-reference-to-video", uno prompt non vuoto e 1–15 ordinati reference_image_urls. Recupera ogni attività con GET al momento della sua creazione percorso seguito da /:id. Le attività completate contengono una serie videos di URL dei risultati. Puoi anche fornire callback_url per il completamento notifiche.

Entrambi gli endpoint accettano il numero intero duration_seconds compreso tra 3 e 16, predefinito 5 e output_resolution di 540p, 720p, 1080p, 2k o 4k, predefinito 720p. audio è un booleano JSON, true predefinito; esplicito false disabilita l’audio generato. I prompt accettano fino a 20.000 personaggi. La richiesta di conversione da immagine a video è facoltativa e rappresenta il primo fotogramma ne determina le proporzioni. Il riferimento al video accetta aspect_ratio di 16:9, 9:16, 1:1, 4:3 o 3:4, 16:9 predefinito e fino a 3 reference_audio_urls.

Utilizza URL multimediali pubblici HTTP(S). Le immagini devono essere JPG/JPEG, PNG o WEBP; l’immagine del primo fotogramma non deve essere più grande di 50 MB. Ogni audio di riferimento il file deve essere MP3, lungo 3-12 secondi e non più grande di 50 MB. RunAPI controlla i tipi di campo, gli schemi URL e i conteggi dei riferimenti. La generazione il provider controlla il formato, le dimensioni e la durata dell’audio del supporto remoto in modo asincrono. I supporti non validi possono causare il fallimento dell’attività tramite il file normale flusso di guasti e rimborsi.

Prezzi immagine in video. Prezzi riferimenti in video.