Geração de vídeo

Buscar /

Os modelos de vídeo respondem como tarefas, não como uma única resposta. POST /v1/videos devolve um id de tarefa com "status": "queued", e GET /v1/videos/{task_id} informa o progresso até a tarefa chegar a completed ou failed. Ao concluir, o arquivo final é a URL assinada em metadata.url; ela carrega um parâmetro Expires, então baixe o arquivo em vez de guardar o link. Uma tarefa que falha traz o código e a mensagem do provedor em error.code e error.message, o que costuma bastar para descobrir qual campo faltou na requisição. POST /v1/video/generations chega ao mesmo handler, para clientes já escritos para esse caminho.

POST /v1/videos

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-i2v",
    "prompt": "the cat turns and walks toward the camera",
    "input_reference": "https://example.com/first-frame.jpg",
    "size": "1280*720",
    "duration": 5
  }'

# {"id":"task_9f2c...","task_id":"task_9f2c...","object":"video",
#  "model":"wan2.7-i2v","status":"queued","progress":0}

GET /v1/videos/{task_id}

curl https://api.chinaapi.ai/v1/videos/task_9f2c... \
  -H "Authorization: Bearer $CHINAAPI_KEY"

# {"id":"task_9f2c...","object":"video","model":"wan2.7-i2v",
#  "status":"completed","progress":100,
#  "metadata":{"url":"https://.../output.mp4?Expires=..."}}

Texto para vídeo

wan2.7-t2v

Apenas model e prompt são obrigatórios. Sem size e duration, o gateway envia 1280*720 com cinco segundos.

Imagem para vídeo

wan2.7-i2v

Anime uma imagem estática. input_reference recebe a URL de uma imagem acessível publicamente, que passa a ser o primeiro quadro; envie size e duration junto.

Referência para vídeo

wan2.7-r2v

Monte um vídeo a partir de material de referência. input_reference aceita uma imagem de referência; para enviar várias use images, e video_url acrescenta um vídeo de referência — as referências contam juntas, até cinco. Não envie input_reference e images ao mesmo tempo, porque o gateway mantém apenas input_reference.

Edição de vídeo

wan2.7-videoedit

Edite um clipe existente a partir de um prompt. video_url recebe o vídeo de origem, que precisa ter de 2 a 10 segundos em MP4 ou MOV, e size define a saída.

Vídeo de 30 segundos

doubao-seedance-2-5-260628

As imagens de referência vão em images, e input_reference aceita uma imagem; se você enviar as duas, ambas são mantidas. A duração vai em seconds ou duration, e os parâmetros do fornecedor vão em metadata, onde resolution é 480p ou 720p.

Seedance 2.0

doubao-seedance-2-0-260128

Mesmo formato de requisição de doubao-seedance-2-5-260628, inclusive as regras de role para metadata.content. doubao-seedance-2-0-fast-260128 e doubao-seedance-2-0-mini-260615 trocam qualidade por velocidade e custo, e a linha 2.0 exige ao menos uma referência de imagem ou vídeo, enquanto a 2.5 também aceita só áudio.

Kling 3.0

kling-v3

O primeiro quadro vai em image; esta família nunca lê input_reference. mode vale std por padrão e duration, 5 segundos. O resto fica em metadata: image_tail para um quadro final, sound como on ou off (off por padrão), além de negative_prompt, cfg_scale e camera_control.

Faixa econômica

kling-3.0-turbo

Envie prompt para texto em vídeo, ou acrescente image e o gateway monta o array contents que o provedor espera. O dimensionamento fica em metadata.settings: resolution é 720p ou 1080p, duration vai de 3 a 15 segundos, e aspect_ratio é 16:9, 9:16 ou 1:1. O áudio vem sempre e não tem chave para desligar.

Referência multi-imagem

kling-v3-omni

Geração guiada por várias imagens de referência de uma vez. Todos os parâmetros ficam em metadata, e não existe campo resolution — o nível de qualidade é o mode. Veja o exemplo completo abaixo.

Áudio nativo

MiniMax-H3

Aceita os campos do próprio gateway e monta a carga do provedor para você: image ou input_reference vira o primeiro quadro, images viram imagens de referência, e video_url vira um vídeo de referência. size escolhe 768P ou 2K e duration é um inteiro de 4 a 15. Requisições só de texto precisam de um metadata.ratio explícito diferente de adaptive.

Hailuo

MiniMax-Hailuo-2.3

Junto com MiniMax-Hailuo-2.3-Fast e MiniMax-Hailuo-02. Estes leem do nível raiz apenas prompt, duration e size; toda imagem passa por metadata, como first_frame_image, last_frame_image ou subject_reference.

Faixa 480P

happyhorse-1.1-t2v

Junto com happyhorse-1.1-i2v e happyhorse-1.1-r2v. Os campos são os da família wan2.7 — prompt, input_reference, size, duration — e aqui o 480P tem preço, então 832*480 é aceito onde wan2.7 recusa. Várias referências vão em metadata.input.media, porque a montagem automática que o campo images dispara é exclusiva de wan2.7-r2v.

Dica Escreva size como largura e altura unidas por um asterisco, como em 1280*720. A letra x não é aceita: 832x480 volta como invalid size: 832x480, example: 1920*1080. duration é um número inteiro de segundos. Para wan2.7-i2v, wan2.7-r2v e wan2.7-videoedit, o gateway dobra size em uma faixa de resolução e o provedor só tem duas, então envie 1280*720 para 720P ou 1920*1080 para 1080P. Um tamanho 480P como 832*480 não tem preço nesses três e ou é recusado de imediato, ou é aceito e depois falha no provedor com InvalidParameter; a tarefa que falha é reembolsada, mas de um jeito ou de outro a ida e volta se perde. wan2.7-t2v aceita o valor como está.

Dica A família Kling lê a proporção a partir de size por uma tabela fixa que escreve os tamanhos com a letra x — 1280x720, 1920x1080, 720x1280, 1080x1920, 1024x1024, 512x512 — e o que ela não reconhece vira 1:1 sem erro. Mandar a forma com asterisco 1280*720 para kling-v3 devolve, portanto, um vídeo quadrado em vez de uma reclamação; defina metadata.aspect_ratio diretamente quando o enquadramento importa.

Dica MiniMax-Hailuo-2.3, MiniMax-Hailuo-2.3-Fast e MiniMax-Hailuo-02 descartam os campos de raiz image, input_reference, images e video_url sem avisar: a requisição tem sucesso, mas roda como texto em vídeo e é cobrada assim. Coloque a imagem em metadata.first_frame_image, use metadata.last_frame_image para um quadro final, e metadata.subject_reference para referências de personagem. MiniMax-H3 é a exceção da família e de fato lê os campos de raiz.

kling-v3-omni · multi-image reference

curl https://api.chinaapi.ai/v1/video/generations \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "the character from the references walks through a neon-lit street",
    "metadata": {
      "image_list": [
        {"image_url": "https://example.com/character.jpg"},
        {"image_url": "https://example.com/outfit.jpg"},
        {"image_url": "https://example.com/scene.jpg"}
      ],
      "mode": "std",
      "duration": "5",
      "aspect_ratio": "16:9",
      "sound": "off"
    }
  }'

GET /v1/video/generations/{task_id}

curl https://api.chinaapi.ai/v1/video/generations/task_9f2c... \
  -H "Authorization: Bearer $CHINAAPI_KEY"

# {"code":"success",
#  "data":{"task_id":"task_9f2c...","status":"SUCCESS",
#          "progress":"100%","fail_reason":"",
#          "result_url":"https://.../output.mp4"}}

Dica Uma imagem de referência não leva type; o campo existe só para marcar first_frame ou end_frame, e aspect_ratio passa a ser obrigatório sempre que não houver primeiro quadro. mode é o nível de qualidade — std, pro ou 4k — e o padrão do provedor é pro, cobrado a 1,33x o preço de tabela, enquanto 4k é cobrado a 5x; envie mode explicitamente para que a cobrança seja a esperada. duration é uma string de "3" a "15" e sound vem como off. Um vídeo de referência vai em video_list e precisa definir "refer_type": "feature": o modo de edição base é cobrado pela duração do vídeo enviado, não pode ser precificado antes do envio, e por isso é recusado. As imagens de referência também têm um tamanho mínimo no provedor: um arquivo do tamanho de um ícone passa no envio e só então faz a tarefa falhar com Image pixel is invalid; a tarefa que falha é reembolsada, mas a ida e volta se perde.

Dica Os dois caminhos relatam o resultado em formatos diferentes. GET /v1/videos/{task_id} responde no formato de vídeo da OpenAI, onde o arquivo é metadata.url e o progresso é um número. GET /v1/video/generations/{task_id} responde {"code": "success", "data": {…}}, onde o arquivo é data.result_url, data.status é uma palavra em maiúsculas como SUCCESS ou FAILURE, data.progress é uma string como "100%", e a falha se explica em data.fail_reason. Consulte o mesmo caminho pelo qual você enviou.

doubao-seedance-2-5-260628 · first frame

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "the subject slowly turns toward the camera",
    "images": ["https://example.com/first-frame.jpg"],
    "seconds": "5",
    "metadata": {"resolution": "480p"}
  }'

doubao-seedance-2-5-260628 · reference mode

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "keep the subject from the reference image",
    "seconds": "5",
    "metadata": {
      "resolution": "480p",
      "ratio": "16:9",
      "content": [
        {
          "type": "image_url",
          "image_url": {"url": "https://example.com/reference.jpg"},
          "role": "reference_image"
        }
      ]
    }
  }'

Dica Uma imagem sem role é lida como primeiro quadro, não como referência: a saída segue a proporção daquela imagem, enviar ratio junto é recusado com InvalidParameter.TaskTypeConstraint, e um seconds igual a 2 também é recusado nesse modo, enquanto 5 funciona. generate_audio é true por padrão no provedor, então o arquivo volta com faixa de áudio a menos que você o defina como false em metadata. Marque cada parte de metadata.content com um role para alcançar o modo de referência completo — até 30 imagens, 10 vídeos e 10 trechos de áudio, entrada só de áudio, e 30 segundos de uma vez — onde ratio é aceito.