Guide de migration
Deux plateformes peuvent proposer la même tâche et diverger sur les noms de champs, les valeurs par défaut, les états terminaux, le sens des erreurs et la définition d’une unité facturée. Une migration qui commence par l’URL de base découvre tout cela en production.
L’enjeu
Seul le modèle se porte proprement. Ce qui ne se porte pas, c’est tout le reste : quels champs sont obligatoires, quelles valeurs par défaut s’appliquent, comment une image de référence entre, quand l’argent est réservé, et ce que votre code doit faire d’un état inconnu.
01
Écrivez la correspondance point d’accès par point d’accès plutôt que de la déduire. L’entrée est validée contre le schéma publié avec additionalProperties fermé : un champ non mappé est un 400 à la première vraie requête, pas un avertissement dans un journal.
02
createTask réserve l’estimation et la renvoie dans cost avec settled: false. Si votre fournisseur actuel ne facture qu’en cas de succès, votre rapprochement doit comprendre les réservations avant tout déplacement de trafic.
03
Neuf valeurs couvrent tous les échecs, content_rejected compris : un refus est une tâche terminale, pas une exception. Mappez vos branches d’erreur existantes sur ces neuf avant la bascule, pas après.
La méthode
Prenez un seul flux, relevez ses entrées, sorties, échecs et coûts unitaires actuels, et rejouez les mêmes conditions ici. Comparez l’estimation de jobs/quote à ce que vous payez aujourd’hui, gardez les deux chemins actifs derrière un drapeau et n’augmentez la part que tant que les chiffres tiennent.
Estimez d’abord : mêmes contrôles de validation et d’admission que la création, sans réservation ni génération.
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"
}
}Contrat
| Champ ou en-tête | Valeur ou 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 |
Balayez horizontalement pour voir toutes les colonnes.
Intégration
Pertinence
Vérifications
POST /api/v1/jobs/quote effectue les mêmes contrôles de validation et d’admission que la création, renvoie estimatedCost, maxCharge, quantity et unit, et ne réserve rien. L’estimation signée reste valable cinq minutes.
Envoyez quoteId et expectedCost avec la création. Si le prix a changé entre-temps, l’admission renvoie le code métier 40901 avant toute réservation.
Un nom d’appel publié reste valable ; un renommage conserve une 308 et un alias. Votre table de correspondance ne pourrit pas en silence entre deux versions.
Avant la mise en production
Questions fréquentes
Modèles
Chaque lien ouvre la page de la famille de modèles concernée : entrées, limites, politique de contenu et prix actuel à l’unité.
Et après
Déplacez un flux à la fois : correspondance des champs, états et erreurs normalisés, factures comparées, bascule avec un retour arrière éprouvé.
Source: fal model APIs ↗