Soluzione API video
Il video è la generazione più costosa e più lenta della maggior parte dei prodotti. Tre campi nel corpo della richiesta decidono entrambi i numeri, e l’attività continua a girare molto dopo che la richiesta che l’ha avviata è sparita.
La sfida
Una richiesta video non è una richiesta immagine più lenta. Durata, risoluzione e l’interruttore dell’audio stabiliscono quanto paghi e quanto aspetti, e lo fanno prima che esista un solo fotogramma.
01
La maggior parte degli endpoint video fattura al secondo di output alla risoluzione scelta. Portare duration_seconds da 5 a 10 raddoppia più o meno l’addebito, e uno scatto di risoluzione lo raddoppia di nuovo. Entrambi sono marcati come campi che influiscono sul prezzo nello schema dell’endpoint, quindi la stima sta accanto al comando, non sulla fattura.
02
Dove esiste, generate_audio è un booleano che sposta la richiesta su un’altra tariffa. Un modulo che lo nasconde spedisce in silenzio la versione più cara di ogni richiesta.
03
createTask risponde 202 Accepted con un taskId in stato queued. La generazione prosegue lato server per minuti. Tutto ciò che resta in attesa sul socket originale va in timeout mentre l’attività, e l’addebito, proseguono.
L’approccio
Chiedi il preventivo del corpo esatto con POST /api/v1/jobs/quote, mostra la stima restituita, poi manda lo stesso corpo a createTask con quoteId, expectedCost e una Idempotency-Key salvata. Un prezzo cambiato fra le due chiamate fallisce con il codice applicativo 40901 invece di riapparire dopo come sorpresa.
Una sola chiamata di creazione porta il modello, l’input validato e una callback facoltativa. HTTP 202 significa accettata, non completata.
POST /api/v1/jobs/createTask
POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Idempotency-Key: 7b1f0c2e-9a4d-4f31-8c67-2b5e0d9a1c44
Content-Type: application/json
{
"model": "<publisher>/<model>/text-to-video",
"input": {
"prompt": "A slow aerial drift over a misty pine forest at sunrise",
"duration_seconds": 5,
"resolution": "1080p",
"generate_audio": true
},
"callBackUrl": "https://example.com/hooks/spicyapi"
}202 Accepted
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
{
"code": 200,
"msg": "success",
"request_id": "req_example_create",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "queued",
"estimatedCost": "0.750000"
}
}Contratto
| Campo o header | Valore o limite |
|---|---|
| POST /api/v1/jobs/createTask | 202 Accepted · state queued |
| duration_seconds · resolution · generate_audio | price-affecting fields |
| Idempotency-Key | 24 h · scoped to one API key |
| output.assets[].expiresAt | signed URL · results kept 14 days |
Scorri in orizzontale per vedere tutte le colonne.
Integrazione
Scelta
Verifiche
Il modulo di ogni pagina del modello è generato dall’input_schema di quell’endpoint, e il server valida sullo stesso documento. Un campo che il modello non dichiara restituisce 400 invece di essere scartato.
createTask blocca la stima e la restituisce come cost con settled: false. L’addebito finale non supera mai il blocco, e un’attività fallita o scaduta lo libera per intero.
Limita una chiave al giorno, al mese e per tutta la sua vita, restringila a modelli e IP di origine indicati, e manda ogni scrittura con la stessa chiave di idempotenza.
Prima del lancio
Domande frequenti
Modelli
Ogni link apre la pagina di quella famiglia di modelli: input, limiti, politica sui contenuti e prezzo attuale per unità.
Continua
Confronta gli endpoint video per durata, risoluzione, audio e prezzo, poi invia la stessa richiesta dal tuo server e seguila con l’ID dell’attività.
