Guia de migração
Duas plataformas podem oferecer a mesma tarefa e ainda assim divergir em nomes de campo, valores padrão, estados terminais, significado dos erros e no que conta como unidade cobrada. Uma migração que começa pela URL base descobre tudo isso em produção.
O desafio
O que porta limpo é só o modelo. O que não porta é tudo em volta: quais campos são obrigatórios, quais são os padrões, como uma imagem de referência entra, quando o dinheiro é reservado e o que o seu código deve fazer com um estado que nunca viu.
01
Escreva o mapeamento endpoint por endpoint em vez de deduzir. A entrada é validada contra o esquema publicado com additionalProperties fechado, então um campo não mapeado é 400 na primeira requisição real, não um aviso em log.
02
createTask reserva a estimativa e a devolve em cost com settled: false. Se o seu fornecedor atual só cobra no sucesso, a conciliação precisa entender reservas antes de mover tráfego.
03
Nove valores cobrem toda falha, content_rejected incluído: uma recusa é tarefa terminal, não exceção. Mapeie seus ramos de erro para esses nove antes da virada, não depois.
A abordagem
Pegue um único fluxo, registre entradas, saídas, falhas e custo unitário atuais e rode as mesmas condições aqui. Compare a estimativa de jobs/quote com o que você paga hoje, mantenha os dois caminhos vivos atrás de uma flag e só aumente a fatia enquanto os números se sustentarem.
Estime primeiro: passa pela mesma validação e admissão da criação, sem reservar fundos nem começar a gerar.
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 ou cabeçalho | Valor 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 |
Deslize horizontalmente para ver todas as colunas.
Integração
Adequação
Evidências
POST /api/v1/jobs/quote roda a mesma validação e admissão da criação, devolve estimatedCost, maxCharge, quantity e unit e não reserva nada. A estimativa assinada vale cinco minutos.
Envie quoteId e expectedCost na criação. Se o preço mudou no meio, a admissão devolve o código de negócio 40901 antes de reservar qualquer valor.
Um nome publicado continua válido; uma renomeação mantém 308 e apelido. Sua tabela de mapeamento não apodrece em silêncio entre versões.
Antes de lançar
Perguntas frequentes
Modelos
Cada link abre a página daquela família de modelos: entradas, limites, política de conteúdo e o preço atual por unidade.
A seguir
Mova um fluxo por vez: mapeie campos, normalize estados e erros, compare a fatura e vire o tráfego com um retorno que você testou.
Fonte: fal model APIs ↗