Guía de migración
Dos plataformas pueden ofrecer la misma tarea y no coincidir en nombres de campo, valores por defecto, estados terminales, significado de los errores y qué es una unidad facturada. Una migración que empieza por la URL base descubre todo eso en producción.
El reto
Lo único que se porta limpio es el modelo. Lo que no se porta es todo lo que hay alrededor: qué campos son obligatorios, qué valores por defecto rigen, cómo entra una imagen de referencia, cuándo se reserva el dinero y qué debe hacer tu código con un estado que nunca ha visto.
01
Escribe el mapeo endpoint por endpoint en lugar de deducirlo. La entrada se valida contra el esquema publicado con additionalProperties cerrado, así que un campo sin mapear es un 400 en la primera petición real, no un aviso en un registro.
02
createTask reserva la estimación y la devuelve en cost con settled: false. Si tu proveedor actual solo cobra al tener éxito, tu conciliación debe entender las reservas antes de mover tráfico.
03
Nueve valores cubren todos los fallos, content_rejected incluido: un rechazo es una tarea terminal, no una excepción. Mapea tus ramas de error existentes a esos nueve antes del cambio, no después.
El enfoque
Toma un solo flujo, registra sus entradas, salidas, fallos y coste unitario actuales y ejecuta las mismas condiciones aquí. Compara la estimación de jobs/quote con lo que pagas hoy, mantén ambos caminos vivos tras una bandera y sube el porcentaje solo mientras los números aguanten.
Estima primero: pasa la misma validación y admisión que la creación, sin reservar fondos ni empezar a generar.
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"
}
}Contrato
| Campo o cabecera | Valor o límite |
|---|---|
| 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 |
Desliza horizontalmente para ver todas las columnas.
Integración
Encaje
Comprobaciones
POST /api/v1/jobs/quote ejecuta la misma validación y admisión que la creación, devuelve estimatedCost, maxCharge, quantity y unit, y no reserva nada. La estimación firmada vale cinco minutos.
Envía quoteId y expectedCost con la creación. Si el precio cambió entre medias, la admisión devuelve el código de negocio 40901 antes de reservar nada.
Un nombre publicado sigue siendo válido; un cambio de nombre conserva un 308 y un alias. Tu tabla de mapeo no se pudre en silencio entre versiones.
Antes del lanzamiento
Preguntas frecuentes
Modelos
Cada enlace abre la página de esa familia de modelos: entradas, límites, política de contenido y el precio actual por unidad.
Siguiente paso
Mueve un flujo cada vez: mapea campos, normaliza estados y errores, compara la factura y cambia con una vuelta atrás que hayas probado.
Fuente: fal model APIs ↗