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

Os campos status_url e content_url nas respostas de criação e consulta são os caminhos oficiais relativos à URL base; use-os diretamente. As rotas de compatibilidade somente para leitura GET /v1/videos/generations/{id} e GET /v1/videos/generations/{id}/content também consultam o mesmo trabalho. Esses caminhos não aceitam criação nem exclusão.

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_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "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_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "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_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "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.
• Um HTTP 404 durante a consulta não significa que a geração falhou e não deve causar um novo envio. Guarde o ID original, confira o status_url retornado ou use GET /v1/videos/tasks/{id} e uma API Key válida da conta proprietária do trabalho. O vídeo pode já ter sido concluído e cobrado; confira os detalhes de uso. Se ainda não conseguir consultar, informe ao suporte o ID e o horário do envio.
• 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, vídeos de referência do Seedance 2.5 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. Na geração orientada por quadros, o último quadro exige o primeiro quadro.
• Papel de vídeo de referência do Seedance 2.5: reference_video; imagens de referência comuns fornecidas junto usam reference_image.
• 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
  }'

Na geração orientada por quadros, é permitido enviar apenas o primeiro quadro. O último quadro exige 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 a partir de texto e dos quadros inicial/final. Ao usar somente imagens para orientar a geração, indique os papéis de quadro explicitamente. Seedance 2.5 também aceita o modo com vídeos de referência descrito abaixo.

{
  "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": "adaptive",
  "duration": 6,
  "generate_audio": true
}

Os valores padrão do Seedance 2.5 para geração a partir de texto são 480p, 9:16, 4 segundos e áudio gerado ativado. O modo de quadro inicial ou inicial/final sem vídeos de referência segue a proporção da primeira imagem: defina ratio como adaptive ou omita o campo; o alias aspect_ratio segue a mesma regra. Uma proporção fixa explícita, como 16:9, retorna 400 invalid_request em vez de ser alterada silenciosamente. Um quadro inicial vertical produz um vídeo vertical. Para obter saída em 16:9, recorte ou expanda primeiro a imagem inicial para 16:9 e use adaptive. A geração a partir de texto e o modo com vídeos de referência continuam aceitando proporções fixas como 16:9.

Seedance 2.5: vídeos de referência

Envie o JSON abaixo para POST https://api.icodeeasy.cc/v1/videos/generations, com Authorization: Bearer <sua API Key> e Content-Type: application/json:

{
  "model": "doubao-seedance-2.5",
  "prompt": "Siga o movimento de @Video1 para gerar um vídeo fluido",
  "content": [
    { "type": "video_url", "video_url": "https://cdn.example.com/reference.mp4", "role": "reference_video" }
  ],
  "resolution": "480p",
  "ratio": "9:16",
  "duration": 4,
  "generate_audio": true
}

Substitua o URL de exemplo por um URL HTTPS de vídeo acessível publicamente. Passe uma string de URL diretamente em video_url; duration é a duração da saída. O serviço lê a duração do vídeo de referência, portanto não é necessário enviar um campo de duração da entrada. Adicione vários vídeos a content, cada um com reference_video; @Video1, @Video2 e assim por diante no prompt seguem a ordem dos vídeos na lista.

• Entrada: até 10 vídeos MP4/MOV, de 2–30 segundos cada, no máximo 30 segundos no total e 100 MiB por arquivo.
• Saída: 4–30 segundos em 480p ou 720p. É possível definir ratio e generate_audio; não use parâmetros exclusivos do Motion Control.
• É possível fornecer também até 2 imagens com type: "image_url", uma string em image_url e role: "reference_image". Neste modo, as imagens são referências comuns, sem garantia de quadro inicial ou final; os papéis de quadro também são tratados como referências comuns.
• Os vídeos devem usar H.264/H.265 a 24–60 fps, com largura e altura de 300–6000 pixels cada, 409.600–8.295.044 pixels no total (largura × altura) e proporção largura/altura de 0,4–2,5. 720×720 atende a esses limites de dimensão.

Após a criação ser aceita, consulte o mesmo trabalho pelo status_url retornado ou por GET /v1/videos/tasks/{id}. O download funciona como nos outros modelos. A cobrança de vídeos de referência inclui a entrada de referência e a saída; veja a seção de cobrança abaixo.

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_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "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 de um trabalho de vídeo comum = 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 sem vídeos de referência, 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. Vídeos de referência do Seedance 2.5 seguem as regras de reserva e liquidação do valor real abaixo, em vez de considerar apenas a duração da saída.

A criação reserva o valor estimado e o deduz do saldo disponível; por isso, o saldo diminui enquanto a geração ainda está em andamento. Saldo insuficiente retorna 402 antes do início da geração. No sucesso, o valor final e a diferença em relação à reserva são liquidados, e os detalhes de uso são registrados; cost_rmb é a cobrança final. Uma falha confirmada devolve toda a reserva. A diferença de saldo entre solicitações consecutivas pode incluir reservas ou devoluções de vídeos e não é necessariamente o custo daquela solicitação.

Cobrança de vídeos de referência do Seedance 2.5

O modo com vídeos de referência reserva uma estimativa usando “duração total dos vídeos de referência arredondada para cima até um segundo inteiro + segundos de saída” e a tarifa estimada para vídeos de referência na página de preços. Por exemplo, um vídeo de referência de 2 segundos com saída de 4 segundos reserva uma estimativa para 6 segundos; isso não garante o preço final.

A cobrança final segue o uso real: a diferença abaixo do valor reservado é devolvida, e a diferença acima dele é debitada adicionalmente. cost_rmb e os detalhes de uso mostram a cobrança final. Uma falha confirmada devolve toda a reserva. Se o progresso permanecer em 99%, o trabalho pode estar aguardando a liquidação da cobrança; continue consultando o trabalho original e não envie novamente.

Kling 4

kling-v4: 720p / 1080p, duração inteira de 3–30 segundos (padrão 5). Áudio sempre ligado; generate_audio: false é rejeitado localmente. Campo exclusivo omni_reference_task_type: auto / reference / edit / extend. Proporções: 16:9 / 9:16 / 1:1 / 21:9; auto apenas em referência. Omita ratio na extensão. Suporta primeiro/último quadro, até 8 imagens e 5 vídeos; cada vídeo de 3–30 segundos, total até 30. Edição/extensão aceitam um vídeo. Sem duration na edição, usa-se a duração de entrada arredondada para cima; os outros modos usam 5 segundos por padrão. Toda mídia, incluindo primeiro/último quadro, usa asset_id: envie multipart com kind=image ou kind=video e file para POST /v1/videos/assets, depois use o id retornado na geração. URLs diretas de imagem/vídeo, áudio de referência e quadros intermediários não são aceitos. Extensão aceita último quadro de destino sem primeiro quadro.

Referências: comum 720p ¥1.0486/s, 1080p ¥1.5729/s; entrada de vídeo 720p ¥0.62916/segundo faturável, 1080p ¥0.94374/segundo faturável. Referência/edição com vídeo cobra segundos de saída + max(segundos de saída, total de entrada arredondado para cima); extensão cobra apenas os segundos adicionados.

{
  "model": "kling-v4",
  "prompt": "Preserve the subject and change the setting",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true,
  "omni_reference_task_type": "edit",
  "content": [
    {
      "type": "video_url",
      "role": "reference_video",
      "asset_id": "vasset_uploaded_video"
    }
  ]
}

Novos modelos de vídeo

Envie toda mídia dos novos modelos como seu próprio asset_id. Limites do site: imagens até 10 MB, vídeos de pelo menos 3 segundos e até 100 MiB. Referências de áudio Q4 e entrada de vídeo Omni Ext indisponíveis nesta versão. Áudio de saída é uma função separada.

FLUX3 Video

FLUX3: texto, imagem e edição de um vídeo, 5–20 segundos (padrão5), hd/fhd. Proporções auto/21:9/2:1/16:9/4:3/1:1/3:4/9:16. Até10 imagens na ordem primeiro→referências intermediárias→último, preservando repetições. Um vídeo de3–30s. draft:true somente HD. Modos auto/t2v/i2v/v2v/draft_enhance. Áudio de saída ligado por padrão; desligado tem o mesmo preço de referência.

Escolha Gerar versão final/Aprimorar no histórico de um rascunho FLUX3 concluído. Envie apenas model, generation_mode:draft_enhance, source_task_id do site e resolution; sem novo prompt, mídia, duração ou áudio. Exige rascunho próprio do mesmo modelo, concluído e liquidado. O custo do rascunho não é creditado.

Vidu

Vidu Q4: primeiro quadro único(prompt opcional) ou1–15 referências(prompt obrigatório, até20000 caracteres), sem texto puro ou último quadro. Uma reference_image já seleciona referências; não misture com primeiro quadro.3–16s,540p/720p/1080p/2K/4K. Q3 exige1–7 referências,prompt até5000 caracteres,3–16s; Mix1–16s,só720p/1080p. Pro/Turbo: texto,primeiro quadro ou primeiro+último,1–16s,540p/720p/1080p. Texto exige prompt até2000 caracteres; imagem é opcional. Todos padrão720p/5s. Referência/texto:1:1/9:16/16:9/3:4/4:3; primeiro quadro segue imagem e omite proporção. Q3/Mix sem controle de áudio; Q4/Pro/Turbo áudio ligado por padrão, desligado no mesmo preço de referência.

Gemini Omni

Gemini Omni principal:360p/720p/1080p/4k,16:9/9:16,até10 imagens com primeiro/último ou referências comuns,e um vídeo3–10s. Preview:só720p,até16 referências comuns,um vídeo3–24s,sem modo primeiro/último; com vídeo omita proporção. Saída definida pelo prompt(3–10s); nunca envie duration,generate_audio,seed,negative_prompt ou n. Referência de saída pode excluir mídia/contexto e não é teto de custo; cobrança pelo uso real.

Escolha Continuar geração no histórico de tarefa própria liquidada com sucesso do mesmo modelo principal/Preview. Novo prompt obrigatório; source_task_id e vídeo são exclusivos. Não insira IDs do fornecedor. Modos auto/t2v/i2v/reference/edit/extend.

Omni Ext:360p/720p/1080p/4k,16:9/9:16,4/6/8/10s(padrão6),preço por clipe. Texto,um primeiro quadro ou exatamente1/3 referências; sem dois quadros,vídeo ou continuação. Prompt obrigatório,modos auto/t2v/frame/reference; sem parâmetro de áudio.

FLUX3 e Omni principal/Preview mostram preços de referência da saída. Mídia/contexto podem acrescentar uso; custo real tem prioridade. Diferenças da reserva são devolvidas ou cobradas.99% pode aguardar liquidação: consulte a tarefa original,sem reenviar.

Preço final de referência em RMB (por segundo)

Preços finais de referência Omni Ext em RMB (por clipe)