Guida alla migrazione
Due piattaforme possono offrire la stessa attività e comunque non essere d’accordo su nomi dei campi, valori predefiniti, stati finali, significato degli errori e cosa sia un’unità di fatturazione. Una migrazione che parte dalla base URL scopre tutto questo in produzione.
La sfida
Il modello è la parte che si porta dietro senza problemi. Quello che non si porta dietro è tutto il resto: quali campi sono obbligatori, quali sono i valori predefiniti, come entra un’immagine di riferimento, quando viene bloccato il denaro e cosa deve fare il tuo codice davanti a uno stato che non ha mai visto.
01
Scrivi la mappatura endpoint per endpoint invece di dedurla. L’input è validato sullo schema pubblicato con additionalProperties chiuso, quindi un campo non mappato è un 400 alla prima richiesta vera e non un avviso in un log.
02
createTask blocca la stima e la restituisce come cost con settled: false. Se la tua piattaforma attuale addebita solo in caso di successo, la riconciliazione deve capire i blocchi prima che tu sposti traffico.
03
Nove valori coprono ogni fallimento, e content_rejected è uno di questi: un rifiuto è un’attività terminata, non un’eccezione. Mappa i tuoi rami di errore su quei nove prima del passaggio, non dopo.
L’approccio
Prendi un solo flusso di lavoro, registra i suoi input, output, fallimenti e costo unitario attuali, e ripeti le stesse condizioni qui. Confronta la stima di jobs/quote con quello che paghi oggi, tieni vive entrambe le strade dietro un flag e alza la quota solo finché i numeri tengono.
Prima il preventivo: esegue le stesse validazioni e gli stessi controlli di ammissione della creazione, senza bloccare fondi né avviare lavoro.
POST /api/v1/jobs/quote
{
"model": "<publisher>/<model>/text-to-video",
"input": {
"prompt": "A slow aerial drift over a misty pine forest at sunrise",
"duration_seconds": 5,
"resolution": "1080p"
}
}200 OK — nothing reserved, nothing started
{
"code": 200,
"msg": "success",
"request_id": "req_example_quote",
"data": {
"quoteId": "qte_01k3m8x9q2z4v7n5p6r8s0t1w3",
"model": "<publisher>/<model>/text-to-video",
"estimatedCost": "0.750000",
"maxCharge": "0.750000",
"currency": "USD",
"quantity": "5",
"unit": "second",
"expiresAt": "2026-09-12T12:05:00Z"
}
}Contratto
| Campo o header | Valore o limite |
|---|---|
| POST /api/v1/jobs/quote | no hold · signed quote valid 5 min |
| quoteId + expectedCost | 40901 when the price moved |
| 402 | 40201 balance · 40202 spend cap |
| published call name | immutable · renames keep a 308 |
Scorri in orizzontale per vedere tutte le colonne.
Integrazione
Scelta
Verifiche
POST /api/v1/jobs/quote esegue le stesse validazioni e gli stessi controlli di ammissione della creazione, restituisce estimatedCost, maxCharge, quantity e unit e non blocca nulla. Il preventivo firmato resta valido cinque minuti.
Manda quoteId ed expectedCost con la creazione. Se il prezzo è cambiato nel frattempo, l’ammissione restituisce il codice applicativo 40901 prima che venga bloccato qualcosa.
Un nome di chiamata pubblicato resta valido; una rinomina mantiene un 308 e un alias. La tua tabella di mappatura non marcisce in silenzio fra una release e l’altra.
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
Sposta un flusso alla volta: mappa i campi, normalizza stati ed errori, confronta la fattura e sposta il traffico con un rollback già provato.
Fonte: fal model APIs ↗