A Video API está em Alfa e a Batch API em Beta (veja Maturidade dos recursos). As duas são ativadas por espaço de trabalho sob solicitação. Configurações → Prévia de recursos mostra se o seu espaço de trabalho tem acesso a elas; ativar uma preferência pessoal na web não concede acesso à API. As cobranças normais de uso de modelos se aplicam.
id e a polling_url dele e, depois, aguarde um webhook ou consulte até o trabalho chegar a um estado final: completed, failed, cancelled ou expired. Uma resposta de criação bem-sucedida significa apenas que o trabalho foi aceito.
Mantenha o caminho de consulta (polling) mesmo quando usar webhooks. Enquanto essas APIs estiverem em Alfa e Beta, comece com solicitações pequenas e um limite de gastos na chave de API. Entradas de referência, cancelamento e retenção das saídas dependem do provedor e do modelo. Salve a sua própria cópia das saídas concluídas antes que expirem.
Receba atualizações
Associe um endpoint de webhook do seu espaço de trabalho ao criar qualquer um dos dois tipos de trabalho:batch.completed ou video.failed. Os tipos de evento genéricos job.* continuam funcionando e assinam a fase correspondente para os dois tipos de trabalho.
Verifique e confirme as entregas
Verifiquex-phaseo-signature com o segredo do endpoint: é o HMAC-SHA256 em hexadecimal de x-phaseo-timestamp, um ponto literal e o corpo da solicitação sem modificações. Confira se o timestamp é recente, elimine duplicados com base em x-phaseo-event-id e confirme as entregas aceitas com uma resposta 2xx. As entregas podem ser repetidas ou chegar fora de ordem, então recupere o trabalho antes de aplicar uma mudança de estado conflitante.
Uma resposta 2xx encerra a entrega. Varreduras em segundo plano enviam as novas tentativas, então uma nova tentativa pode chegar depois do previsto. Cada tentativa registra o número, o horário, o status HTTP, o erro e o horário da próxima tentativa. Elimine duplicados mesmo assim: uma confirmação perdida ou um worker interrompido podem deixar uma entrega incerta.
Depois de salvar um endpoint, use Enviar evento de teste em Configurações para entregar um payload
webhook.test assinado. Uma entrega de teste é tentada uma única vez, não é repetida e não entra no histórico de entregas dos trabalhos.
Veja os logs de trabalhos e solicitações
Em Configurações → Uso → Registros, use Solicitações para os detalhes das solicitações de inferência, Vídeo para o ciclo de vida dos vídeos e Lote para os trabalhos em lote e os resultados por linha. As visualizações de detalhes de Vídeo e Lote incluem o status de cobrança, as tentativas no provedor e as tentativas de webhook. Um trabalho pode ser concluído com sucesso enquanto a entrega do webhook dele falha. O envio de vídeo reserva crédito antes de contatar o provedor. Um timeout sem ID de tarefa mantém a reserva para reconciliação; isso não é evidência de uma geração com falha. Se uma reserva paga de Video ou Batch for inesperadamente precificada em zero depois de um trabalho bem-sucedido, a cobrança permanece aberta comunexpected_zero_cost para investigação. Uma resposta de criação com custo zero, por si só, é normal na geração assíncrona.
Estime quanto custa um vídeo
Os preços de vídeo dependem do provedor e do modelo. Um preço por segundo precisa ser multiplicado pela duração cobrável; um preço por clipe vale apenas para a duração e a resolução especificadas. Várias saídas e entradas de referência cobráveis podem aumentar o total. A geração de texto/imagem do LTX cobra os segundos de saída, enquanto a de áudio para vídeo cobra os segundos do áudio de entrada. O BytePlus Seedance usa tokens de vídeo, com tarifas diferentes quando há um vídeo de referência. O MiniMax Hailuo V1 usa preços por clipe de duração fixa; o H3 usa segundos e pode cobrar pelas entradas de referência. Verifique as dimensões de preço do provedor selecionado em vez de interpretar um preço de vitrine como o custo de uma solicitação inteira. As reservas são estimativas retidas antes do envio. A cobrança final usa o uso cobrável do trabalho; o crédito reservado não utilizado é liberado após a reconciliação. Uma resolução ou opção compatível com o provedor não garante que ela esteja disponível no beta.Defina duração, frames e referências
Useseconds ou duration para a duração da saída. Se os dois estiverem presentes, precisam concordar. Use resolution com aspect_ratio, ou um size em pixels, como 1280x720.
Use frame_images para definir explicitamente o primeiro e o último frame:
role: "reference" explicitamente para imagens que sejam apenas referência: solicitações legadas sem frame_images interpretam a primeira imagem sem rótulo como primeiro frame. Não combine frame_images com papéis de primeiro/último frame em input_references nem com input_reference.
Referências de vídeo e áudio usam type: "video_url" ou "audio_url" e media_url: { "url": "https://..." }. Modelos e provedores aceitam combinações diferentes. Quando a duração da referência afeta o preço, informe input_video_duration e input_audio_duration em segundos.
Envie opções de vídeo específicas do provedor
Mantenha o modelo, a duração, a resolução, a geração de áudio, a mídia de entrada e o número de saídas nos campos canônicos. Envie extensões específicas do provedor sob o ID canônico do provedor:provider para isso. Não combine provider_options com o legado provider_params. Opções aninhadas não podem substituir campos de cobrança ou de callback controlados pelo Gateway.
O AtlasCloud Seedance usa os campos nativos
resolution, ratio e last_image. A variante de referência para vídeo recebe referências ordenadas de imagem, vídeo e áudio. A edição com duração automática (duration: -1) não é compatível com o contrato de reserva de duração fixa do Gateway. A disponibilidade e os preços do modelo no provedor precisam estar configurados antes que um modelo possa ser roteado; uma opção de provedor não ativa um modelo indisponível.
O MiniMax H3 usa a V2: de 4 a 15 segundos inteiros em 768P ou 2K. O H3 Max aceita de 5 a 15 segundos inteiros em 480P ou 768P, com texto ou imagens de frame. O H3 aceita imagens, vídeo e áudio de referência; referências não podem ser misturadas com primeiro/último frame. Os dois modelos produzem um vídeo por solicitação e não aceitam as opções de otimização de prompt da V1. Use o canônico aspect_ratio; as entradas de frame determinam a própria proporção. As reservas com vídeo de referência cobrem o limite de entrada de 15 segundos do provedor, e o uso real é acertado na conclusão. Consulte o contrato MiniMax V2.
Verifique o que cada provedor de lotes aceita
As solicitações de lote também aceitamprovider_options: a OpenAI aceita output_expires_after e a Mistral aceita metadata. Use IDs canônicos de provedor e não duplique esses campos no nível superior. Por exemplo, provider_options: { "openai": { "output_expires_after": { "anchor": "created_at", "seconds": 86400 } } } define a retenção das saídas da OpenAI. Entradas de linhas, modelos, endpoints e destinos de webhook não podem ser substituídos pelas opções.
A Mistral já tem um adaptador nativo de lotes. Os lotes de mensagens da Anthropic são consultados por polling; outros provedores podem combinar polling com notificações nativas de conclusão. A disponibilidade depende dos endpoints compatíveis do provedor e da lista de permissões de lotes da implantação. Verifique a resposta de capacidade de lotes antes de enviar um arquivo ou solicitações inline.
Os lotes do Vertex Gemini aceitam requests inline com /v1/generateContent, ou model e prompts. Selecione provider: "google-vertex" para usar o Vertex. As linhas bem-sucedidas são cobradas com as tarifas de Batch. Este adaptador exige credenciais gerenciadas; BYOK, Files enviados, embeddings e lotes google-vertex-eu não estão disponíveis. A entrada é limitada a 20 MB e 10.000 solicitações. A entrada e a saída armazenadas expiram após 30 dias.
Os resultados do Vertex usam custom_id para identificar cada linha enviada, com uma geração bem-sucedida em response.body ou um error por solicitação. A ordem da saída pode ser diferente da ordem da entrada. Um envio com resultado incerto no provedor fica em revisão manual com a retenção de crédito mantida; evite criar um substituto até que o resultado seja confirmado.
A conclusão de um lote pode incluir linhas com falha. Inspecione cada resultado pelo custom ID em vez de presumir que todas as linhas funcionaram. Guarde a entrada original e o ID do trabalho até que os resultados e a cobrança estejam reconciliados. Um envio incerto precisa ser investigado antes de um novo envio, porque o provedor pode ter aceitado a solicitação original.
Baixe os resultados do lote
Depois que um lote compatível chega a um estado final, aresults_url dele aponta para um download autenticado do Phaseo. Use a sua chave de API normal do Phaseo, do espaço de trabalho dono do lote:
custom_id para linhas compatíveis com OpenAI e da Anthropic, os metadados da solicitação para o Gemini e batch_request_id para o xAI. As linhas bem-sucedidas da Anthropic contêm a mensagem gerada em result.message.
Os downloads são compatíveis com os adaptadores de OpenAI, Anthropic, Google AI Studio, Mistral, Together, Groq, Alibaba Cloud, Moonshot, Parasail, OVHcloud e xAI. A disponibilidade de provedores ainda depende do acesso à prévia e da lista de permissões de envio; a compatibilidade com download não ativa rotas adicionais. Os endpoints existentes output_file_id, error_file_id e de conteúdo de arquivos continuam disponíveis. O endpoint de linhas de solicitação do lote contém metadados de rastreamento e cobrança, não os corpos das mensagens geradas.
Baixar os resultados não envia outro lote nem gera uma cobrança de inferência. Você não precisa de credenciais do provedor. Os webhooks sinalizam atualizações do trabalho; baixe os resultados separadamente. Um trabalho em estado final pode ter resultados parciais ou nenhuma saída: o endpoint retorna 409 durante o processamento e 404 quando não há saída disponível. Salve os resultados antes que termine o período de retenção do provedor. Se um download for interrompido, descarte o arquivo parcial e repita o download, não o envio do lote. Resultados JSON inline são transmitidos com um limite de segurança de 8 MiB por linha; arquivos JSONL nativos são transmitidos sem esse limite por linha.
Para saídas grandes, client.batches.streamResults(batchId, { signal }) no TypeScript retorna um ReadableStream<Uint8Array> sem armazenar em buffer. Encaminhe-o ao seu destino e cancele o stream ou aborte o sinal para parar antes; não há um tempo limite fixo para o download total. No Python, client.batches.stream_results(batch_id) produz blocos de bytes com o tempo limite HTTP configurado; feche o iterador ao parar antes. As operações geradas retrieveBatchResults retornam o texto JSONL completo e são mais adequadas para saídas pequenas.
Limites de download de lotes
Os downloads de resultados de lotes permitem 10 tentativas por espaço de trabalho por lote em uma janela móvel de 30 minutos, compartilhadas entre as chaves de API e os aliases/batches e /batch. As tentativas que chegam à admissão do download contam mesmo que o download no upstream falhe ou seja cancelado. Falhas de propriedade e de prontidão não contam. Uma resposta 429 inclui Retry-After em segundos. Se o limitador estiver indisponível, os downloads retornam 503 com Retry-After: 30.