Solução de API de vídeo
Vídeo é o resultado mais caro da maioria dos produtos e o que mais demora a voltar. Três campos do corpo decidem as duas coisas, e a tarefa continua viva muito depois de a requisição que a iniciou ter sumido.
O desafio
Uma requisição de vídeo não é uma requisição de imagem mais lenta. Duração, resolução e a chave de áudio definem quanto você paga e quanto espera, e definem antes de existir um único quadro.
01
A maioria dos endpoints de vídeo cobra por segundo produzido na resolução escolhida. Passar duration_seconds de 5 para 10 dobra o valor aproximadamente; subir um degrau de resolução dobra de novo. Ambos vêm marcados como relevantes para o preço no esquema, então a estimativa fica ao lado do controle, não na fatura.
02
Onde existe generate_audio, esse booleano move a requisição para outra tarifa. Um formulário que o esconde vai enviar caladamente a versão mais cara toda vez.
03
createTask responde 202 Accepted com um taskId em queued. A geração segue no servidor por minutos. Qualquer código que espere no socket original vai estourar o tempo enquanto a tarefa, e a cobrança, continuam.
A abordagem
Peça a estimativa do corpo exato com POST /api/v1/jobs/quote, mostre o valor e envie esse mesmo corpo para createTask com quoteId, expectedCost e uma Idempotency-Key guardada. Um preço que mudou entre as duas chamadas falha com o código de negócio 40901 em vez de aparecer depois na fatura.
Uma chamada de criação carrega o modelo, a entrada validada e um retorno opcional. HTTP 202 significa aceito, não concluído.
POST /api/v1/jobs/createTask
POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Idempotency-Key: 7b1f0c2e-9a4d-4f31-8c67-2b5e0d9a1c44
Content-Type: application/json
{
"model": "<publisher>/<model>/text-to-video",
"input": {
"prompt": "A slow aerial drift over a misty pine forest at sunrise",
"duration_seconds": 5,
"resolution": "1080p",
"generate_audio": true
},
"callBackUrl": "https://example.com/hooks/spicyapi"
}202 Accepted
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
{
"code": 200,
"msg": "success",
"request_id": "req_example_create",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "queued",
"estimatedCost": "0.750000"
}
}Contrato
| Campo ou cabeçalho | Valor ou limite |
|---|---|
| POST /api/v1/jobs/createTask | 202 Accepted · state queued |
| duration_seconds · resolution · generate_audio | price-affecting fields |
| Idempotency-Key | 24 h · scoped to one API key |
| output.assets[].expiresAt | signed URL · results kept 14 days |
Deslize horizontalmente para ver todas as colunas.
Integração
Adequação
Evidências
O formulário de cada página de modelo é gerado do input_schema daquele endpoint, e o servidor valida contra o mesmo documento. Um campo não declarado devolve 400 em vez de ser descartado em silêncio.
createTask reserva o valor estimado e o devolve em cost com settled: false. A cobrança final nunca ultrapassa a reserva, e falha ou expiração libera tudo.
Limite uma chave por dia, por mês e ao longo de toda a vida dela, restrinja a modelos específicos e a IPs de origem, e envie cada escrita com a mesma chave de idempotência.
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
Compare endpoints de vídeo por duração, resolução, áudio e preço e envie depois a mesma requisição a partir do seu servidor.
