Tutorial de imagem para vídeo

Tenha uma conta, saldo e uma chave de API

Siga primeiro Prepare sua conta. Quando terminar, você deve ter:

• uma conta na SpicyAPI com dinheiro no saldo;
• uma chave de API, que começa com sk-spicy-;
• essa chave guardada numa variável de ambiente chamada SPICY_API_KEY. Uma variável de ambiente é um valor com nome que o seu terminal entrega aos programas que ele roda; assim, a chave nunca precisa aparecer num comando nem no seu código.

Confira se a chave está definida na janela de terminal que você está usando, sem imprimir a chave inteira:

echo "${SPICY_API_KEY:0:9}"

Deve aparecer sk-spicy-. Se não aparecer nada, ou se aparecer um erro, a chave não está definida nesta janela; volte para Prepare sua conta.

Coloque a sua imagem numa pasta de trabalho

Crie uma pasta para este tutorial e abra o terminal nela. Todos os comandos desta página são rodados a partir dessa pasta, e todos os arquivos que eles criam vão parar ali.

mkdir -p ~/spicy-video
cd ~/spicy-video

Copie a sua imagem para essa pasta e dê a ela o nome start-frame.jpg (ou start-frame.png, se for um PNG; nesse caso, use esse nome em todos os lugares em que esta página diz start-frame.jpg).

O que faz uma boa imagem inicial:

• Formato e tamanho: JPEG, PNG, WebP ou GIF, com até 10 MiB (cerca de 10 megabytes). Um modelo pode definir limites próprios mais rígidos, que você vai ver no passo 1.
• O arquivo precisa ser mesmo desse formato. A SpicyAPI confere o conteúdo do arquivo, não só o nome. Fotos de celular muitas vezes são HEIC, e renomear uma delas para .jpg não a converte. Abra a foto e exporte ou salve como JPEG primeiro.
• Proporção: a imagem vira o primeiro quadro do vídeo. Use uma imagem horizontal para um vídeo horizontal e uma vertical para um vídeo vertical; alguns modelos também oferecem a configuração aspect_ratio.
• Direitos: use uma imagem que você tenha permissão para usar.

Prepare a ferramenta que você escolheu

npm install -g @spicyapi/cli
spicyapi --version

spicyapi balance

1. Escolha um modelo e leia as configurações dele

Faça isto: liste os modelos de imagem para vídeo que a sua conta pode usar, escolha um e depois leia quais configurações ele aceita.

spicyapi models list --modality video --task image-to-video --json

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example video model",
      "modality": "video",
      "tasks": ["image-to-video"],
      "enabled": true,
      "available": true,
      "quantityField": "duration_seconds",
      "maxOutputDurationSeconds": 10,
      "taskTimeoutSeconds": 1800,
      "pricing": [
        { "variant": "720p", "unit": "per_second", "price": "…", "currency": "USD" },
        { "variant": "1080p", "unit": "per_second", "price": "…", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

O que olhar na lista:

Como ler as configurações. inputSchema é a lista de configurações do modelo, escrita em JSON Schema:

• required lista as configurações que você precisa enviar. Neste tipo de modelo, image_url sempre está entre elas, e a maioria também exige prompt.
• properties lista todas as configurações que o modelo aceita, cada uma com um type, uma description em inglês simples e, muitas vezes, enum (os únicos valores permitidos), minimum e maximum, e default (usado quando você deixa a configuração de fora).
• Dentro de cada configuração, x-ui guarda dicas de exibição. x-ui.affects_price: true quer dizer que mudar essa configuração muda o preço.
• Alguns modelos acrescentam condições no nível mais alto do schema, como "se você enviar A, também precisa enviar B". O Spicy Schema explica como lê-las.
• examples traz entradas completas que o servidor já conferiu, um ponto de partida seguro.

As configurações que você vai encontrar com mais frequência. Os nomes são os mesmos em todos os modelos, mas cada modelo aceita só algumas delas, com os seus próprios valores permitidos:

O que aconteceu: você leu o catálogo atual da sua conta, com os seus preços. Nada foi cobrado. Ler o catálogo conta para o limite de requisições da sua conta, então não é preciso repetir isso antes de cada vídeo; faça de novo quando trocar de modelo ou receber um 400.

2. Envie a sua imagem

Faça isto: envie start-frame.jpg e copie o endereço spicy:// que voltar. O upload é gratuito.

spicyapi files upload start-frame.jpg

fileId: fil_01k3m8x9q2z4v7n5p6r8s0t1w3
status: ready
bytes: 402118
contentType: image/jpeg
sha256: a91f4c2e5b7d16809e3f2a4c8d0b61e7c4a890e5d2f71b3c609ae8427d15f0c6
uri: spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3
expiresAt: 2026-09-18T09:12:11Z

O que aconteceu: a sua imagem foi guardada de forma privada para a sua conta, conferida (o formato real dela precisa corresponder ao tipo informado) e recebeu um endereço spicy://. Esse endereço não é um link da web: só a sua conta pode usá-lo, e só dentro da entrada de uma tarefa. Ele pode ser usado por um dia (veja expiresAt); depois disso, envie a imagem de novo.

Se o upload falhar:

3. Descreva o vídeo e confira o preço

Faça isto: escreva as suas configurações num arquivo chamado input.json e depois peça uma cotação.

Escreva o input.json. Comece com as duas configurações que todo modelo de imagem para vídeo aceita. Coloque a sua própria frase em prompt e troque o valor de image_url pelo uri que você copiou no passo 2:

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}

As configurações que você deixar de fora usam o default do modelo. Para escolhê-las você mesmo, acrescente só configurações que as properties do seu modelo listam, com valores que ele permite. Por exemplo, se o seu modelo lista duration_seconds e resolution e permite estes valores:

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5,
  "resolution": "720p"
}

Salve o arquivo na sua pasta de trabalho:

cat > input.json <<'EOF'
{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}
EOF

Use aspas retas comuns ("), não aspas curvas, e não coloque vírgula depois da última configuração.

Peça a cotação:

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json

quoteId: eyJ2IjoxLCJtIjoi…
model: MODEL_ID_FROM_CATALOG
estimatedCost: …
maxCharge: …
currency: USD
quantity: 5
unit: per_second
expiresAt: 2026-09-17T08:05:00Z

O que aconteceu: a SpicyAPI conferiu a sua entrada com as configurações do modelo e calculou o preço desta requisição exata. Nada foi iniciado e nada foi cobrado. estimatedCost é o valor que vai ser reservado se você iniciar agora, e maxCharge é o máximo que pode custar. quantity e unit mostram pelo que você paga, como 5 segundos.

Uma cotação vale por cinco minutos e só para esta entrada exata. Mude a duração ou a resolução e peça outra cotação para comparar preços. A cotação faz as mesmas verificações que iniciar a tarefa, então os problemas aparecem aqui sem custo: um 400 quer dizer que a entrada não corresponde às configurações do modelo (corrija o input.json com base no passo 1), e um 40201 quer dizer que o seu saldo não cobriria o valor. O passo 7 lista os outros códigos.

4. Inicie a geração

A chave de idempotência, em palavras simples. É um rótulo para um vídeo, como um número de pedido. Se a sua conexão cair e você não tiver certeza de que o vídeo começou, envie a mesma requisição de novo com o mesmo rótulo: a SpicyAPI devolve a tarefa que já tinha iniciado em vez de iniciar, e cobrar, uma segunda. Um rótulo vale por 24 horas com a mesma chave de API. Use um rótulo novo para outro vídeo: o mesmo rótulo com uma entrada diferente é recusado com 409. Mais em Idempotência.

Faça isto:

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json

Estimated charge: USD …; maximum charge: USD …. Quote expires: 2026-09-17T08:05:00Z.
Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
Create a billable task with model MODEL_ID_FROM_CATALOG? … Continue? [y/N]

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
taskId: job_01k3m8x9q2z4v7n5p6r8s0t1w3
state: queued
estimatedCost: …
deadlineAt: 2026-09-17T08:35:00Z

O que aconteceu: a SpicyAPI aceitou a geração, que agora é uma tarefa, e separou estimatedCost do seu saldo. Esse é também o máximo que este vídeo pode custar. state: queued quer dizer que a tarefa está esperando a vez dela. deadlineAt é o horário limite para ela terminar; se não estiver pronta até lá, ela acaba como expired, e nada é cobrado. deadlineAt não é quando os seus arquivos expiram.

Passar a cotação adiante quer dizer "só aceite isto pelo preço que me mostraram". Se o preço ou a entrada tiverem mudado nesse meio-tempo, a requisição é recusada com 40901 em vez de reservar outro valor. A CLI faz isso por você.

Se a conexão caiu e você nunca viu um ID de tarefa, não comece simplesmente de novo com um rótulo novo: isso criaria, e cobraria, um segundo vídeo. Repita a requisição com o mesmo rótulo:

• CLI: spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key <the value you copied>, trocando <the value you copied> pelo valor que você copiou. Veja Retomar uma tarefa depois que a espera foi interrompida.
• SDK: rode node generate.mjs --yes de novo; ele reaproveita o idempotency-key.txt.
• HTTP: rode de novo o bloco "Iniciar o vídeo"; ele reaproveita o idempotency-key.txt.

Se o passo 4 foi recusado, nada foi criado e nada foi cobrado; o motivo e a solução estão no passo 7.

5. Espere o vídeo ficar pronto

Faça isto: consulte a tarefa até ela terminar. Vídeos costumam levar alguns minutos.

spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000 --json

{
  "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "model": "MODEL_ID_FROM_CATALOG",
  "state": "succeeded",
  "output": {
    "assets": [
      {
        "key": "tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4",
        "url": "https://…",
        "expiresAt": "2026-09-17T08:40:00Z",
        "mime": "video/mp4",
        "durationSeconds": 5,
        "width": 1280,
        "height": 720,
        "bytes": 4839211
      }
    ]
  },
  "cost": "…",
  "settled": true
}

O que aconteceu: a sua ferramenta perguntou à SpicyAPI sobre a tarefa a cada poucos segundos. Os estados são queued (esperando), running (sendo gerada) e depois um estado final: succeeded, failed ou expired. Depois do sucesso, o arquivo é copiado para o armazenamento da própria SpicyAPI, o que leva mais alguns segundos; até lá, o resultado mostra pending: true. cost é definitivo quando settled é true.

• Fechar o terminal ou apertar Ctrl + C não cancela a tarefa. Só interrompe a espera. Guarde o ID da tarefa e rode este passo de novo mais tarde.
• Não consulte com mais frequência do que a cada poucos segundos. Consultar uma tarefa usa a capacidade de leitura da conta, independentemente do envio de tarefas; veja Limites de requisição.
• Para um aplicativo ou um servidor, deixe a SpicyAPI avisar você quando a tarefa terminar, em vez de ficar perguntando: veja Receba um aviso em vez de esperar.

6. Baixe e guarde o vídeo

Faça isto: obtenha um link de download novo e salve o arquivo no seu computador.

spicyapi files download-url job_01k3m8x9q2z4v7n5p6r8s0t1w3

key: tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4
url: https://…
expiresAt: 2026-09-17T08:52:00Z

curl -L -o my-video.mp4 "PASTE_THE_URL_HERE"

O que aconteceu: todo resultado vem com um link de download direto. O link funciona por cerca de 20 minutos e não precisa de chave de API; nunca acrescente a sua chave a ele. Quando ele expirar, consulte a tarefa de novo (ou use files download-url) para obter um link novo.

7. Quando algo dá errado

Os problemas são de dois tipos, e cada um é tratado de um jeito.

Uma requisição é recusada. O seu comando ou a sua chamada recebe um erro na hora. Nada foi criado e nada foi cobrado. A mensagem diz o motivo, e o erro traz um code e um ID de requisição (req_…) para você informar se falar com o suporte.

A tarefa falha. A tarefa foi aceita, mas termina como failed ou expired em vez de succeeded. A tarefa mostra um errorCode, que diz o motivo, e uma errorMessage, com mais detalhes em palavras. Tarefas que falham ou expiram normalmente liberam toda a reserva. Algumas recusas de conteúdo são cobradas pelo orçamento aceito, somente quando a página do modelo informa explicitamente essa exceção. Confira settled e cost para saber o valor final.

Para lê-los:

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Depois decida o que fazer pelo errorCode, não pela redação da mensagem:

Qualquer outro valor deve ser tratado como upstream_failed. A lista completa está em Erros.

Rode de novo uma tarefa que falhou. Uma nova tentativa cria uma tarefa nova, com o mesmo modelo e a mesma entrada, pelo preço atual do modelo. Ela custa dinheiro, como o passo 4, e mantém a entrada original: se essa entrada usava um upload que já expirou, envie o arquivo de novo e inicie uma tarefa nova.

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait --wait-timeout-ms 1800000

Só tarefas failed e expired podem ser repetidas. Para ter outra versão de um vídeo que deu certo, volte ao passo 3 com um rótulo novo. Não existe jeito de cancelar uma tarefa depois que ela foi aceita. Mais em Execução e novas tentativas.