API de geração de vídeo

A API de geração de vídeo cria trabalhos de vídeo assíncronos. Uma solicitação de criação retorna HTTP 202 com um ID de trabalho; use esse ID para consultar o trabalho até ele chegar a succeeded ou failed e, em seguida, baixe o MP4 concluído.

Os exemplos usam https://api.icodeeasy.cc como URL base. Todas as chamadas de endpoint documentadas abaixo exigem sua chave de API; a única exceção é uma URL assinada do arquivo de resultado retornada após o sucesso:

Authorization: Bearer <your API key>

Endpoints

Início rápido em cinco minutos

1. Crie um trabalho

curl -X POST https://api.icodeeasy.cc/v1/videos/generations \
  -H 'Authorization: Bearer <your API key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2.5",
    "prompt": "uma rua de cidade futurista sob a chuva, câmera avançando lentamente, reflexos de neon no asfalto molhado",
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 4,
    "generate_audio": true
  }'

A criação retorna HTTP 202:

{
  "id": "vid_1785398400000000000",
  "task_id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "queued",
  "model": "doubao-seedance-2.5",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:00:00Z"
}

Use task_id como o identificador recomendado para consulta, download e exclusão; id permanece com o mesmo valor durante o período de compatibilidade. Uma resposta 202 significa que o trabalho foi aceito, não que o vídeo já está concluído.

2. Consulte o trabalho

Copie o task_id da resposta de criação para TASK_ID:

TASK_ID='vid_1785398400000000000'
curl "https://api.icodeeasy.cc/v1/videos/tasks/${TASK_ID}" \
  -H 'Authorization: Bearer <your API key>'

Consulte aproximadamente uma vez a cada 5 segundos. Não crie outro trabalho enquanto o atual estiver em queued ou running.

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "running",
  "model": "doubao-seedance-2.0",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:00:20Z",
  "progress": 42
}

progress é uma estimativa e pode não estar presente. Considere status, e não o progresso, como a informação oficial.

3. Baixe o vídeo

Depois que status se tornar succeeded, a resposta incluirá url e o cost_rmb final:

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "succeeded",
  "model": "doubao-seedance-2.0",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:01:18Z",
  "progress": 100,
  "url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "cost_rmb": 0.528
}

Baixe pela rota canônica de conteúdo autenticado e siga os redirecionamentos:

TASK_ID='vid_1785398400000000000'
curl -L "https://api.icodeeasy.cc/v1/videos/tasks/${TASK_ID}/content" \
  -H 'Authorization: Bearer <your API key>' \
  -o result.mp4

A rota de conteúdo aceita HTTP Range e os cabeçalhos condicionais de download mais comuns. Solicitar o conteúdo antes do sucesso retorna 409 video_not_ready.

Ciclo de vida do trabalho e novas tentativas seguras

Regras para novas tentativas:

• Depois de receber HTTP 202, continue consultando o task_id retornado. Repetir a solicitação de criação pode criar outro trabalho.
• Solicitações GET de consulta e download podem ser repetidas com segurança.
• Se a criação retornar submission_unknown, não envie outra solicitação. O trabalho pode já ter sido aceito; entre em contato com o suporte informando o horário, o modelo e um resumo do prompt.
• Depois de uma falha terminal confirmada em failed, crie um novo trabalho somente quando quiser gerar outro vídeo.

Webhooks e callback_url não são compatíveis. Em vez disso, consulte o endpoint do trabalho.

Referência da solicitação de criação

Coloque todas as instruções de texto em prompt. Use content somente para imagens e vídeos de referência.

Lista de mídias de referência (content)

content é uma lista porque um trabalho pode precisar de quadro inicial e final, várias imagens de referência sem ordem ou uma imagem e um vídeo para Motion Control. Informe diretamente uma string de URL HTTPS no campo image_url ou video_url de cada item.

[
  { "type": "image_url", "image_url": "https://cdn.example.com/first.png", "role": "first_frame" },
  { "type": "image_url", "image_url": "https://cdn.example.com/last.png", "role": "last_frame" }
]

• Tipos de imagem: image_url ou input_image.
• Tipos de vídeo: video_url ou input_video.
• Papéis de quadro: first_frame e last_frame. Um último quadro sempre exige um primeiro quadro.
• Papéis de movimento: um reference_image e um reference_video.
• As imagens de referência do Grok não têm papel; reference_image também é aceito.
• No momento, áudio de referência não é compatível.
• A mídia deve usar uma URL HTTPS pública que permaneça válida enquanto o trabalho a lê.
• Coloque imagens em image_url e vídeos em video_url.

Solicitação completa com primeiro e último quadro

Hospede as duas imagens em URLs HTTPS públicas e coloque essas URLs diretamente em content:

curl -X POST https://api.icodeeasy.cc/v1/videos/generations \
  -H 'Authorization: Bearer <sua chave de API>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "a câmera se move suavemente do primeiro para o último quadro",
    "content": [
      {"type":"image_url","image_url":"https://cdn.example.com/first.png","role":"first_frame"},
      {"type":"image_url","image_url":"https://cdn.example.com/last.png","role":"last_frame"}
    ],
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 4,
    "generate_audio": true
  }'

É permitido enviar apenas o primeiro quadro. Não é permitido enviar o último quadro sem incluir o primeiro quadro na mesma solicitação.

Receitas por modelo

Seedance: texto, primeiro quadro e último quadro

Seedance 2.5, Seedance 2.0 Standard, Fast, Mini e Seedance 1.5 Pro aceitam geração de vídeo a partir de texto e geração orientada pelo primeiro e/ou último quadro. Imagens de referência exigem papéis de quadro explícitos; Seedance 2.5 aparece primeiro nesta família.

{
  "model": "doubao-seedance-2.5",
  "prompt": "the camera circles a glass sculpture as morning light changes",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/seedance-first.png", "role": "first_frame" },
    { "type": "image_url", "image_url": "https://cdn.example.com/seedance-last.png", "role": "last_frame" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 6,
  "generate_audio": true
}

Os valores padrão do Seedance 2.5 são 480p, 9:16, 4 segundos e áudio gerado ativado. Com o primeiro quadro ou primeiro e último quadros, a proporção é normalizada para adaptive.

MiniMax H3: texto, primeiro quadro e último quadro

MiniMax-H3 aceita geração de texto para vídeo e com primeiro/último quadro pela mesma solicitação pública. Aceita 768P ou 2K, durações de 4 a 15 segundos e as proporções 21:9, 16:9, 4:3, 1:1, 3:4 e 9:16. Os valores padrão são 768P, 9:16 e 5 segundos. Não envie generate_audio: o contrato público do H3 não tem uma alternância de solicitação para áudio gerado.

Kling: geração orientada por quadros

{
  "model": "kling-v3",
  "prompt": "a train enters the station through light fog",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/kling-first.png", "role": "first_frame" },
    { "type": "image_url", "image_url": "https://cdn.example.com/kling-last.png", "role": "last_frame" }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true
}

Diferenças importantes entre os modelos Kling:

• kling-v2-6: o último quadro exige 1080p; o áudio gerado só está disponível em 1080p e não pode ser combinado com um último quadro.
• kling-3.0-turbo: somente o primeiro quadro; sem áudio gerado.
• kling-v3 e kling-v3-omni: aceitam primeiro/último quadro e áudio gerado.
• kling-v3-omni também aceita até duas imagens de referência sem papel, mas não misture imagens sem papel com imagens que tenham papéis de quadro na mesma solicitação.
• kling-video-o1: primeiro/último quadro; sem áudio gerado.

Grok: imagens de referência sem ordem

O Grok aceita até sete URLs de imagens de referência. Não atribua os papéis first_frame ou last_frame.

{
  "model": "grok-imagine-1.5-video",
  "prompt": "clouds roll over a canyon while the camera rises",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/grok-reference.png" }
  ],
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 6
}

Os valores padrão do Grok são 480p, 9:16 e 6 segundos. Áudio gerado não é compatível.

Kling Motion Control

Forneça uma imagem HTTPS pública e um vídeo MP4 HTTPS público de 3 a 30 segundos:

{
  "model": "kling-v3-motion-control",
  "prompt": "preserve the character identity and follow the reference motion",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/character.png", "role": "reference_image" },
    { "type": "video_url", "video_url": "https://cdn.example.com/motion.mp4", "role": "reference_video" }
  ],
  "motion_mode": "std",
  "character_orientation": "image",
  "keep_original_sound": true
}

• character_orientation: "image": o vídeo de referência deve ter de 3 a 10 segundos.
• character_orientation: "video": o vídeo de referência deve ter de 3 a 30 segundos.
• Não envie resolution, ratio, duration ou generate_audio com um modelo Motion Control.

Tabela de recursos dos modelos

Para modelos padrão, os valores opcionais omitidos usam os padrões de cada modelo exibidos acima. O próprio model é sempre obrigatório. O serviço valida as combinações antes de iniciar o trabalho.

Comportamento da resposta e do download

Todas as respostas de trabalho usam este formato:

Prefira GET /v1/videos/tasks/{id}/content em vez de presumir um formato fixo para a URL retornada. Use -L ou ative redirecionamentos no seu cliente HTTP. O endpoint autenticado de conteúdo pode retornar 200, 206 Partial Content ou um redirecionamento para armazenamento gerenciado pelo relay.

Uma URL assinada de arquivo do relay pode ser aberta sem uma chave de API; quem possuir a URL completa terá acesso ao vídeo. Não a exponha em logs públicos, páginas ou ferramentas de análise no cliente.

Excluir um trabalho terminal seguro retorna HTTP 204 e também pode remover seu arquivo de vídeo gerenciado pelo relay. Baixe e armazene qualquer resultado necessário antes de excluir o trabalho. A exclusão é rejeitada com 409 video_delete_unsafe enquanto um trabalho estiver em execução ou a cobrança não estiver liquidada. Excluir o registro local do trabalho não cancela uma geração que já começou.

Tratamento de erros

Os erros HTTP usam este formato:

{
  "error": {
    "type": "invalid_request",
    "message": "model is not supported"
  }
}

Uma resposta de trabalho com falha pode ter este formato:

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status": "failed",
  "model": "doubao-seedance-2.0",
  "error": { "code": "generation_failed" }
}

Cobrança

A geração de vídeo usa o saldo da conta, e não a cota mensal.

preço do trabalho = preço exibido em RMB por segundo para o modelo/especificação selecionado × segundos faturáveis

Consulte os preços atuais por segundo na página de preços. A resolução, o áudio gerado ou o modo Motion Control podem selecionar uma linha diferente de preço por segundo. Para modelos padrão, os segundos faturáveis correspondem à duration solicitada; para Motion Control, correspondem à duração detectada do vídeo de referência, arredondada para cima até um segundo inteiro.

O saldo deve ser suficiente para cobrir o trabalho no momento da criação. Saldo insuficiente retorna 402 antes do início da geração. O cost_rmb do trabalho concluído com sucesso é a cobrança final oficial. Um trabalho que comprovadamente falhou não é cobrado.