Integração em produção

Escolha o modelo e o protocolo

Leia inputSchema e exemplos no catálogo autenticado. enabled e available precisam ser true. Uma página pública não comprova que a sua conta pode executar o modelo. Tarefas nativas usam /api/v1; clientes compatíveis usam /v1. Cookies do Console não são credenciais de API.

Prepare a entrada no servidor

Mantenha a chave no backend, fora do navegador, de aplicativos distribuídos e de repositórios públicos. Respeite tipos, opções e requisitos condicionais do esquema atual. No fluxo de upload gerenciado, solicite a autorização, faça PUT e commit e use a referência retornada. Você também pode usar uma URL pública ou dados Base64 quando o schema do modelo e o campo aceitarem esse formato. Valide novamente ao trocar de modelo.

Confirme o preço antes do envio

Envie model, input e callBackUrl completos para jobs/quote. Mostre estimatedCost, maxCharge, currency e expiresAt. A cotação vale por cinco minutos e não reserva saldo. Após a confirmação, acrescente quoteId e expectedCost à mesma solicitação. Mudanças ou 40901 exigem nova cotação; não aceite aumentos silenciosamente. Preserve os valores como decimais.

Registre a operação de negócio

Antes de enviar, grave o ID da operação, um hash seguro da requisição e Idempotency-Key; depois acrescente taskId e request_id. Reutilize a chave por 24 horas para a mesma conta, chave API e operação. Timeout não comprova rejeição. Repetir uma tarefa com falha terminal cria outra tarefa nas condições atuais.

Processe callbacks e resultados

Valide assinatura e horário com os bytes originais, elimine duplicatas e persista o evento. Responda rapidamente e envie o trabalho demorado para sua fila. Trate notificações atrasadas ou repetidas conforme o estado. Use recordInfo com espera exponencial limitada como alternativa. 202 significa aceito, succeeded confirma a geração e settled=true a liquidação.

Controle concorrência e retenção

Limite tarefas em andamento por conta e defina prazos nas requisições. Respeite Retry-After em 429 e evite consultar tudo a cada segundo. Use cache privado e curto para o catálogo. URLs assinadas duram 20 minutos; resultados ficam armazenados por 14 dias e uploads, por um dia. As URLs de resultado incluídas nas respostas dispensam uma chamada adicional para obter o arquivo. Arquive o que precisar guardar. Desconectar não cancela uma tarefa aceita.

Valide antes de disponibilizar

Confira catálogo, saldo e cotação antes de uma geração mínima com confirmação de custo. Teste sucesso, entrada inválida, saldo insuficiente, recuperação com a mesma chave, callbacks duplicados, links vencidos e orçamento. Registre request_id, taskId, horário, estado e valor; não grave chaves nem prompts completos.

Fluxos relacionados

Cotações e compatibilidade · Modelos e endpoints · Upload e download de mídia · Webhooks · Erros e novas tentativas · Diagnóstico e recuperação