01
Proporção que não bate custa caro em silêncio
Se a referência é 1:1 e você pede um clipe 16:9, o endpoint precisa colocar barras, cortar ou esticar. Alinhe a referência ao aspect_ratio ou à resolution que vai pedir antes de enviar.
Guia de integração
Anime um quadro parado em que você já confia.
Imagem para vídeo tira a variável mais difícil — como a cena é — e a troca por outra mais estreita: como ela deve se mover. O quadro de referência faz quase todo o trabalho, e por isso o prompt não salva uma referência fraca.
O desafio
O quadro de referência decide a maior parte do resultado
Endpoints de movimento herdam tudo do primeiro quadro: enquadramento, luz, proporção, artefatos. Uma referência mole ou mal cortada gera um clipe mole e mal cortado, e a tarifa é de vídeo.
02
Alguns endpoints também aceitam um quadro final
Onde last_image_url é declarado, fornecer as duas pontas define começo e fim em vez de uma deriva aberta. Onde não é declarado, enviá-lo dá 400.
03
Campos de movimento só existem onde são declarados
movement_amplitude, camera_fixed, fps e duration_seconds aparecem conforme o endpoint, e o esquema marca quais mexem na tarifa. Não existe embaixo um vocabulário de movimento comum.
A abordagem
Fixe o quadro primeiro e pague pelo movimento uma vez só
Faça o trabalho de imagem parada num endpoint de imagem, onde cada iteração custa centavos, fixe o quadro e só então pague pelo movimento. Passar um upload spicy:// confirmado mantém a referência idêntica byte a byte entre tentativas, então uma repetição parte exatamente dos mesmos pixels.
O corpo é uma chamada de criação com campo de imagem. O acompanhamento é igual ao de qualquer outra tarefa de mídia.
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>/image-to-video",
"input": {
"prompt": "Slow push-in, fabric moving in a light breeze",
"image_url": "https://example.com/reference.png",
"duration_seconds": 5,
"resolution": "720p"
},
"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
O que vale fixar logo de início
| Campo ou cabeçalho | Valor ou limite |
|---|---|
| image_url · last_image_url | declared per endpoint |
| POST /api/v1/jobs/retry | new task · source record untouched |
| state | queued · running · succeeded · failed · expired |
| audio / video upload | ≤ 100 MiB · ≤ 600 s |
Deslize horizontalmente para ver todas as colunas.
Integração
Da primeira chamada até produção
- 01Produza ou envie o quadro de referência na proporção que pretende renderizar.
- 02Leia no esquema image_url, duration_seconds, resolution e os campos de movimento declarados.
- 03Estime, envie com Idempotency-Key e URL de retorno e guarde o taskId junto da referência.
- 04No retorno terminal, baixe output.assets e mantenha a referência ao lado do clipe para poder repetir.
Adequação
Quando este caminho é o certo
Escolha se
- A direção de arte já está fechada num quadro parado e você quer movimento sem sortear a cena de novo.
- O mesmo personagem ou produto precisa aparecer idêntico em todos os clipes.
Procure outro caminho se
- A cena ainda não existe. Iterar em quadros parados custa uma ordem de grandeza menos do que iterar em clipes.
- Você precisa de continuidade ao longo de muitos planos. Estes endpoints devolvem clipes curtos, um plano por vez.
Evidências
O que você mesmo pode verificar
Referências se comportam igual em toda parte
URLs HTTPS, uploads spicy:// confirmados e data URIs embutidas funcionam do mesmo jeito em endpoints de imagem e de vídeo, sob os mesmos limites e as mesmas checagens de admissão.
Uma nova tentativa cria outra tarefa e nunca altera a antiga
POST /api/v1/jobs/retry monta uma tarefa a partir de uma que falhou ou expirou e reavalia esquema, preço, permissões e disponibilidade. O registro de origem fica intacto.
Um autômato de estados serve à integração inteira
queued, running, succeeded, failed, expired. As mesmas cinco palavras descrevem todo endpoint de mídia, então a lógica de transição se escreve uma vez.
Antes de lançar
Comportamentos da plataforma a confirmar
- Alinhe a proporção da referência à saída antes do lançamento, não nos chamados de suporte.
- Mantenha a referência acessível durante toda a vida da tarefa, não só no momento do envio.
- Dê às novas tentativas o próprio escopo de idempotência; repetir é criar tarefa nova, não reenviar a antiga.
- Inclua as tarifas de vídeo no teto diário obrigatório da chave.
Perguntas frequentes
O que mais perguntam nesta página
A decisão é sua e a responsabilidade legal também. A plataforma não inspeciona identidade em uploads, e os termos colocam consentimento e direitos do lado do cliente.
O primeiro quadro ancora o resultado, mas cada endpoint segura isso com rigor diferente. Cada página de modelo descreve o comportamento e os controles disponíveis.
Aumente duration_seconds dentro do que o endpoint permitir, ou gere planos separados e monte você mesmo. A duração tem limite por endpoint e é cobrada por segundo.
Você recebe um registro terminal com errorCode estável, a reserva é liberada por inteiro e uma nova tentativa cria outra tarefa a partir da mesma origem sem tocar no registro original.
Modelos
Modelos que você pode chamar para isso
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.
AlibabaWan 3.0Imagem para vídeoPolítica de conteúdo: Sem censuraByteDanceSeedance 2.5Referência para vídeoPolítica de conteúdo: Sem censuraKlingKling 3.0Animação de personagemPolítica de conteúdo: Com filtroByteDanceSeedance 2.5 SpicyImagem para vídeoPolítica de conteúdo: Sem censuraAlibabaWan 3.0 PrimeReferência para vídeoPolítica de conteúdo: Sem censuraKlingKling 2.6Animação de personagemPolítica de conteúdo: Com filtro
A seguir
Testar um endpoint de imagem para vídeo
Transforme uma imagem de referência em clipe. O que a qualidade do primeiro quadro, a proporção, os campos de movimento e a duração fazem.