Guida all’integrazione
Il passaggio da immagine a video toglie la variabile più difficile – che aspetto ha la scena – e la sostituisce con una più stretta: come deve muoversi. Il fotogramma di riferimento fa quasi tutto il lavoro, ed è per questo che un riferimento debole non è qualcosa che il prompt possa salvare.
La sfida
Gli endpoint di movimento ereditano tutto dal primo fotogramma: composizione, luce, proporzioni, artefatti. Un riferimento sfocato o tagliato male produce una clip sfocata e tagliata male, e la paghi a tariffa video.
01
Se il riferimento è 1:1 e chiedi una clip 16:9, l’endpoint deve aggiungere bande, tagliare o deformare. Allinea il riferimento all’aspect_ratio o alla resolution che stai chiedendo prima di inviare, non dopo aver pagato la ripresa.
02
Dove last_image_url è dichiarato, fornire entrambi gli estremi dà un inizio e una fine definiti invece di una deriva libera. Dove non è dichiarato, inviarlo è un 400.
03
movement_amplitude, camera_fixed, fps e duration_seconds compaiono endpoint per endpoint, e lo schema segnala quali di questi spostano la tariffa. Sotto non c’è un vocabolario del movimento condiviso.
L’approccio
Fai il lavoro sul fermo immagine su un endpoint immagine, dove un’iterazione costa centesimi, blocca il fotogramma e solo allora paga il movimento. Passare un upload spicy:// confermato tiene il riferimento identico byte per byte fra un tentativo e l’altro, così una ripetizione parte esattamente dagli stessi pixel.
Il corpo è una chiamata di creazione con un campo immagine. La metà di tracciamento è identica a quella di qualsiasi altra attività media.
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>/image-to-video",
"input": {
"prompt": "Slow push-in, fabric moving in a light breeze",
"image_url": "https://example.com/reference.png",
"duration_seconds": 5,
"resolution": "720p"
},
"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 |
|---|---|
| image_url · last_image_url | declared per endpoint |
| POST /api/v1/jobs/retry | new task · source record untouched |
| state | queued · running · succeeded · failed · expired |
| audio / video upload | ≤ 100 MiB · ≤ 600 s |
Scorri in orizzontale per vedere tutte le colonne.
Integrazione
Scelta
Verifiche
URL HTTPS, upload spicy:// confermati e data URI inline si comportano allo stesso modo su endpoint immagine e video, con gli stessi limiti e gli stessi controlli di ammissione.
POST /api/v1/jobs/retry costruisce un’attività nuova da una fallita o scaduta e rivaluta schema, prezzo, permessi e disponibilità. Il record di partenza resta esattamente com’era.
queued, running, succeeded, failed, expired. Le stesse cinque parole descrivono ogni endpoint media, quindi la logica delle transizioni la scrivi una volta sola.
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
Trasforma un’immagine di riferimento in una clip. Cosa fanno la qualità del primo fotogramma, le proporzioni diverse, i campi di movimento e la durata.
