API de Geração de Vídeo Seedance 2.5

Guia detalhado do APIMaster para parâmetros do Seedance 2.5, mídia de referência, primeiro e último quadro, edição, resultados assíncronos, faturamento e solução de problemas.

Geração de Vídeo Seedance 2.5

Crie vídeos a partir de texto, imagens, vídeo ou referências de áudio usando o ID do modelo público seedance-2.5. A geração é assíncrona: envie uma solicitação, salve seu ID de tarefa pública, consulte até que ela termine e baixe o resultado. Uma submissão bem-sucedida significa que a tarefa foi aceita; não significa que um vídeo já foi gerado.

Importante para tarefas de quadro, edição e extensão: a proporção padrão é adaptive. Mantenha esse valor ou omita a proporção; não envie explicitamente uma proporção fixa como 16:9. Para uma tarefa de primeiro/último quadro apenas com imagem, a saída segue as proporções da primeira imagem. Recorte ou adicione preenchimento à sua imagem primeiro se precisar de uma proporção específica.

Mudanças padrão — 2026-10-01: omitir duration agora significa 5 segundos em vez de 4; a proporção padrão é adaptive em vez de 16:9; o áudio gerado padrão é true. Defina esses campos explicitamente se sua integração depender de uma duração, proporção ou saída silenciosa fixa.

Limites de duração (verificados em 2026-10-06)

duration é a duração do vídeo de saída em segundos: um inteiro de 4 a 30. A geração normal aceita duration: -1 para duração automática. A edição (omni_reference_task_type: "edit") exige -1 e um vídeo de origem de 4–30 segundos.

No máximo 10 vídeos de referência, cada um com 2–30 segundos e total de até 30 segundos; áudio de referência tem os mesmos limites de duração e quantidade. Entrada e saída têm limites separados. Os segundos faturáveis podem incluir ambos, sem aumentar o limite de saída.

Confira os parâmetros antes de enviar. HTTP 200 e task_id confirmam apenas a aceitação; um HTTP 400 / InvalidParameter posterior pode fazer a tarefa falhar. Leia o erro, corrija os parâmetros e crie uma nova tarefa. Não repita a solicitação sem alterações. Tarefas com falha devolvem a reserva da geração.

Fonte de verificação: Seedance API.

Autenticação e endpoints

A URL base da API é https://apimaster.ai/v1. Obtenha uma chave APIMaster em Chaves da API e envie Authorization: Bearer YOUR_API_KEY. Solicitações JSON também precisam de Content-Type: application/json. Mantenha as chaves no seu servidor, não em código público de frontend.

Método	Endpoint	Propósito
`POST`	`https://apimaster.ai/v1/videos/generations`	Submissão de tarefa JSON recomendada
`GET`	`https://apimaster.ai/v1/video/generations/{task_id}`	Status de tarefa em formato de compatibilidade
`GET`	`https://apimaster.ai/v1/videos/{task_id}`	Status de vídeo no estilo OpenAI
`GET`	`https://apimaster.ai/v1/videos/{task_id}/content`	Download de vídeo autenticado
`GET`	`https://apimaster.ai/v1/videos/{task_id}/last-frame`	Download do último quadro autenticado, quando solicitado

Não use um endpoint de tarefa de imagem para consultar um vídeo. Use uma chave pertencente à conta que criou a tarefa.

Início rápido: texto para vídeo

Comece com um clipe curto e uma especificação explícita antes de solicitar 30 segundos ou resolução mais alta. Substitua as URLs de mídia de exemplo nos exemplos posteriores por seus próprios arquivos diretamente baixáveis.

curl --fail-with-body -sS "https://apimaster.ai/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A lighthouse above a calm sea at sunrise. Slow camera push-in, natural lighting, no text.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "adaptive",
    "generate_audio": true,
    "watermark": false,
    "output_format": "mp4"
  }'

Exemplo de resposta de submissão:

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_example"}],
  "error": null
}

Salve o task_id retornado e use o endpoint de consulta para obter o status da tarefa e o vídeo final.

Parâmetros da solicitação e padrões

Campo	Tipo	Padrão	Contrato
`model`	string	Nenhum; obrigatório	`seedance-2.5`
`prompt`	string	Nenhum; obrigatório para geração	Intenção de cena, movimento, câmera e referência; omita ao usar `draft_task_id`
`duration`	integer	`5`; omitido em `edit` torna-se `-1`	`4`–`30` segundos ou `-1` para duração automática; edição aceita apenas `-1`
`resolution`	string	`720p`; prévia `480p`; atualização de prévia `1080p`	Geração ordinária: `480p`, `720p`, `1080p`; prévia e atualização aceitam apenas suas respectivas resoluções
`aspect_ratio`	string	`adaptive`	`adaptive`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`; tarefas de quadro/editar/estender requerem `adaptive`
`ratio`	string	Igual a `aspect_ratio`	Alias; ambos os valores devem corresponder se fornecidos juntos
`size`	string	`adaptive` quando omitido	Campo de conveniência de tamanho/proporção legado; `adaptive` é aceito. Prefira `resolution` e `aspect_ratio`
`image_urls`	string[]	Sem referências	No máximo `30` imagens no total, incluindo `image_with_roles`
`image_with_roles`	object[]	Sem referências	Objetos com `url` e `role`; `first_frame`, `last_frame`, ou `reference_image`
`first_frame_image` / `last_frame_image`	string	Sem quadro	Aliases para as funções de imagem correspondentes; use HTTP(S) ou uma URL aprovada do `asset://`
`video_urls`	string[]	Sem referências	No máximo `10`; duração total no máximo `30` segundos
`audio_urls`	string[]	Sem referências	No máximo `10`; duração total no máximo `30` segundos; referências apenas de áudio são suportadas
`generate_audio`	boolean	`true`	Se deve gerar som
`audio`	boolean	Igual a `generate_audio`	Alias; valores de áudio conflitantes retornam 400
`watermark`	boolean	`false`	Se deve solicitar uma marca d'água de conteúdo gerado
`seed`	integer	Selecionado pelo modelo	Preserve `0` como uma semente explícita; uma semente não garante saída idêntica
`output_format`	string	`mp4`	`mp4` ou `mov`; MOV é útil para fluxos de trabalho de edição/extensão. Codec e precisão de cor dependem do arquivo resultante
`omni_reference_task_type`	string	`auto`	`auto`, `reference`, `edit`, ou `extend`; veja a validação síncrona abaixo
`nsfw_check`	boolean	`false`	Moderação opcional de texto/imagem pré-submissão
`return_last_frame`	boolean	`false`	Retornar `last_frame_url` após o sucesso quando o quadro estiver disponível
`draft`	boolean	`false`	Gerar uma prévia de 480p; apenas `seedance-2.5`
`draft_task_id`	string	Não definido	ID público APIMaster de uma prévia bem-sucedida; atualiza para uma nova tarefa de 1080p

Use booleanos JSON, não strings como "false". Aliases conflitantes, resoluções não suportadas, duração inválida e restrições específicas da tarefa retornam HTTP 400 antes que uma tarefa seja criada ou sua reserva cobrada. Arrays opcionais omitidos significam sem referências.

Campos adicionais e formas de entrada

Campo ou entrada	Suporte da interface
`negative_prompt`	Aceito como texto; incluído na moderação quando `nsfw_check` está habilitado
`first_frame_image` / `last_frame_image`	Aliases de string suportados; não duplique o mesmo quadro em `image_with_roles`
Imagens Base64 / data-URL	Não suportadas como URLs de geração. Faça upload do arquivo através de `/v1/uploads/images` e use a URL retornada
`generation_type`	Aceito como um campo opcional para geração ordinária; use `omni_reference_task_type` para o contrato do tipo de tarefa
`camerafixed`	Aceito como um booleano para geração ordinária; descreva o movimento de câmera necessário no prompt
`service_tier`	Opcional para geração ordinária; rejeitado para ambas as prévias e atualizações de prévia

Não dependa de generation_type, camerafixed, ou service_tier para garantir um resultado visual específico ou prioridade de agendamento. Eles não são substitutos para os requisitos documentados de tipo de tarefa e prompt.

Selecione o tipo de tarefa

Tarefa	Entrada e intenção	Configurações obrigatórias
Texto para vídeo	Prompt sem mídia de referência	Escolha uma proporção, resolução e duração suportadas
Geração por referência	Imagens/vídeo/áudio de referência e uma descrição de uma nova cena	Proporções fixas são possíveis; faça o prompt descrever claramente a geração por referência
Geração de primeiro quadro	Uma imagem com função `first_frame`	`aspect_ratio: "adaptive"`
Geração de primeiro e último quadro	Um `first_frame` e um `last_frame`	`aspect_ratio: "adaptive"`; um último quadro precisa de um primeiro quadro
Edição de vídeo	Vídeo de origem mais um prompt pedindo para editar, remover, substituir ou modificar conteúdo	`aspect_ratio: "adaptive"`, `duration: -1`; vídeo de origem `4`–`30` segundos
Extensão de vídeo	Vídeo de origem mais um prompt pedindo para continuá-lo ou estendê-lo	`aspect_ratio: "adaptive"`; mantenha a mídia de referência dentro dos limites abaixo

omni_reference_task_type pode selecionar explicitamente auto, reference, edit ou extend. Use um prompt correspondente: declarar reference enquanto pede para substituir um objeto ainda pode levar a uma incompatibilidade de tipo de tarefa. Para edição, a duração omitida é normalizada para -1; a proporção omitida é adaptive. Valores explícitos devem satisfazer as mesmas restrições. Para geração por referência, evite instruções de edição ou extensão, a menos que essa seja sua operação pretendida.

Validação síncrona do tipo de tarefa

Tipo declarado	Validação antes da aceitação
`edit`	Pelo menos uma entrada `video_urls`; proporção omitida ou `adaptive`; duração omitida ou `-1`; vídeo de origem `4`–`30` segundos
`extend`	Pelo menos uma entrada `video_urls`; proporção omitida ou `adaptive`
`reference`	Os limites comuns de proporção e duração suportados se aplicam; sem restrição de edição/extensão
`auto`	A intenção da tarefa é inferida a partir do prompt e das referências

A seleção explícita captura parâmetros inválidos no envio: HTTP 400, nenhuma tarefa, nenhuma reserva de geração. A intenção da tarefa também é avaliada durante a geração; um prompt inconsistente com o tipo declarado pode falhar de forma assíncrona com InvalidParameter.TaskTypeMismatch. Escreva um prompt de edição para edit, um prompt de continuação para extend e um prompt de nova cena para reference.

Funções de imagem e primeiro/último quadro

Entradas image_with_roles usam {"url": "https://example.com/frame.png", "role": "first_frame"}. As funções são first_frame, last_frame e reference_image. Use no máximo um primeiro quadro e um último quadro. Imagens de referência orientam a aparência ou composição; elas não forçam um quadro inicial exato. Evite misturar definições sobrepostas de image_urls e image_with_roles.

Se referências de vídeo ou áudio também forem incluídas, as funções de quadro podem ser tratadas como imagens de referência gerais, em vez de uma tarefa estrita de primeiro/último quadro. Use entrada apenas de imagem quando precisar de ancoragem precisa de quadro.

{
  "model": "seedance-2.5",
  "prompt": "The camera moves smoothly from the first view to the last view. Preserve the building and lighting.",
  "image_with_roles": [
    {"url": "https://example.com/first.png", "role": "first_frame"},
    {"url": "https://example.com/last.png", "role": "last_frame"}
  ],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "adaptive",
  "generate_audio": false
}

Para um único quadro inicial, remova a entrada last_frame. Se precisar de uma proporção de saída diferente, corte ou preencha a primeira imagem para essa proporção antes de enviar; alterar apenas aspect_ratio não é suficiente.

Referências de imagem, vídeo e áudio

Dê a cada referência um propósito claro no prompt. As referências são indexadas a partir de 1 na ordem do array; descrições como @图片1, @视频1 e @音频1 podem identificar referências de imagem, vídeo e áudio. Não se refira a um índice que esteja ausente da solicitação.

{
  "model": "seedance-2.5",
  "prompt": "Create a new coastal scene using @图片1 for the color palette, @视频1 for camera movement, and @音频1 for the rhythm. Do not edit or extend the original video.",
  "image_urls": ["https://example.com/palette.png"],
  "video_urls": ["https://example.com/camera-reference.mp4"],
  "audio_urls": ["https://example.com/rhythm.mp3"],
  "omni_reference_task_type": "reference",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "generate_audio": true
}

Para geração de referência apenas de áudio, mantenha audio_urls e remova os arrays de imagem/vídeo. Todas as mídias devem ser acessíveis ao serviço de geração sem login no navegador, cookies ou cabeçalhos de autorização adicionais.

Edite um vídeo

{
  "model": "seedance-2.5",
  "prompt": "Edit the video: replace the red umbrella with a blue umbrella while preserving the subject and camera motion.",
  "video_urls": ["https://example.com/source.mp4"],
  "omni_reference_task_type": "edit",
  "duration": -1,
  "resolution": "720p",
  "aspect_ratio": "adaptive",
  "generate_audio": true,
  "output_format": "mov"
}

A edição segue a duração do clipe de origem. A duração automática pode exigir uma reserva de saldo inicial maior; consulte a cobrança abaixo.

Estenda um vídeo

{
  "model": "seedance-2.5",
  "prompt": "Extend the video forward: the cyclist continues along the same path, keeping the lighting and camera direction consistent.",
  "video_urls": ["https://example.com/source.mp4"],
  "omni_reference_task_type": "extend",
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "adaptive",
  "generate_audio": true
}

Requisitos de mídia de referência

Estes são limites da mídia de entrada, não das dimensões de saída. Um arquivo que é baixado com sucesso ainda pode ser rejeitado porque seu formato real, dimensões, duração ou conteúdo é inadequado.

Entrada	Quantidade	Dimensões e duração	Requisitos do arquivo
Imagens	No máximo `30` imagens de referência; o modo quadro usa uma ou duas imagens	Cada lado `300`–`6000` pixels; proporção largura/altura `0.4`–`2.5`	Cada arquivo abaixo de `30 MB`. JPEG/PNG são recomendados; outros formatos aceitos incluem WebP, BMP, TIFF, GIF, HEIC, HEIF, sujeitos ao suporte de decodificação
Vídeos	No máximo `10`; duração combinada no máximo `30` segundos	Cada clipe `2`–`30` segundos; fonte de edição `4`–`30` segundos. Cada lado `300`–`6000` pixels; proporção `0.4`–`2.5`; contagem de pixels `409600`–`8295044`; `24`–`60` FPS	Cada arquivo no máximo `200 MB`; MP4/MOV com vídeo H.264 ou H.265 e áudio AAC ou MP3; níveis de resolução suportados `480p`, `720p`, `1080p`
Áudio	No máximo `10`; duração combinada no máximo `30` segundos	Cada clipe `2`–`30` segundos	Cada arquivo no máximo `15 MB`; WAV ou MP3

Use URLs de arquivo HTTPS diretas em vez da URL HTML de uma página de compartilhamento. Um nome de arquivo .png não torna uma página de erro HTML uma imagem válida. Certifique-se de que URLs temporárias assinadas permaneçam válidas por tempo suficiente para a tarefa buscar a mídia. Evite redirecionamentos para páginas de login e links restritos por IP ou regras anti-hotlink. Para máxima compatibilidade de imagem, converta o arquivo para JPEG ou PNG RGB e verifique sua largura e altura reais.

Faça upload apenas de mídias que você está autorizado a usar. Verificações de conteúdo podem rejeitar imagens de pessoas realistas ou outro material restrito; não assuma que uma URL publicamente acessível garante aceitação.

Carregar e revisar mídia antes da geração

O APIMaster suporta uploads de arquivos de imagem e a biblioteca de mídia Seedance. Estas são etapas separadas: carregar um arquivo fornece um URL para download; enviar esse URL para a biblioteca inicia a revisão de conteúdo. Somente um ativo da biblioteca aprovado pode ser referenciado com asset:// em uma solicitação de geração. Mídia de referência comum (não de pessoa) ainda pode usar URLs públicas diretas sem um envio para a biblioteca.

A biblioteca é especialmente útil quando você reutilizará um material ou seu URL original é temporário. Após a revisão ser bem-sucedida, reutilize o endereço asset:// retornado; referências futuras usam o material aprovado em vez de exigir que você reenvie seu URL original. Mantenha o material em sua biblioteca pelo tempo que precisar referenciá-lo.

Mídia de pessoa real deve primeiro ser enviada para a biblioteca de mídia e passar pela revisão. Um upload de arquivo bem-sucedido, um URL acessível ou um envio de tarefa de revisão bem-sucedido não significa que o material foi aprovado. Use apenas mídia que você está autorizado a carregar e usar. A aprovação na revisão não garante que toda solicitação de geração posterior passará em suas próprias verificações de conteúdo.

A sequência recomendada é: carregue uma imagem se precisar de um URL de arquivo público → envie o material para revisão → consulte a tarefa de revisão → selecione um ativo Active → envie a geração de vídeo → consulte a tarefa de vídeo. Salve os IDs retornados de cada etapa; use os endpoints de consulta de vídeo documentados para geração de vídeo.

Especificações e preparação do material

A tabela de mídia de referência acima também se aplica aos envios para a biblioteca. Verifique o arquivo decodificado real, não apenas sua extensão. Para Seedance 2.5:

Material	Formatos aceitos	Limite de arquivo	Requisitos técnicos
Imagem	JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF; JPEG/PNG RGB recomendado	Abaixo de `30 MB` por fonte da biblioteca	Largura e altura cada uma de `300`–`6000` pixels; proporção largura/altura de `0.4`–`2.5`
Vídeo	MP4, MOV; vídeo H.264/H.265; áudio AAC/MP3 quando presente	No máximo `200 MB` por arquivo	Cada clipe de `2`–`30` segundos; fonte de edição de `4`–`30` segundos; cada lado de `300`–`6000` pixels; proporção de `0.4`–`2.5`; total de pixels de `409600`–`8295044`; taxa de quadros de `24`–`60` FPS; níveis suportados `480p`, `720p`, `1080p`
Áudio	WAV, MP3	No máximo `15 MB` por arquivo	Cada clipe de `2`–`15` segundos

Um envio de revisão contém 1–20 ativos de um tipo. Este limite de lote difere dos limites de geração: até 30 imagens, 10 vídeos ou 10 clipes de áudio; vídeos referenciados juntos não devem exceder 30 segundos, e áudio referenciado junto não deve exceder 30 segundos. Carregar 20 materiais não permite que todos os 20 vídeos ou clipes de áudio sejam usados em uma geração.

Envie explicitamente model: "seedance-2.5" para fontes de vídeo de até 30 segundos. O padrão de envio para a biblioteca é seedance-2.0, que limita fontes de vídeo individuais a 15 segundos. A ingestão na biblioteca de áudio atualmente tem um limite separado de 15 segundos, conforme explicado abaixo. Materiais aprovados podem ser reutilizados entre Seedance 2.0 e 2.5 quando o modelo solicitado está disponível para sua chave e o material satisfaz os limites desse modelo.

Ingestão na biblioteca de áudio: envie clipes de áudio individuais entre 2 e 15 segundos, mesmo com model: "seedance-2.5". Isto é separado do limite de referência de áudio de 2–30 segundos da geração. Corte ou divida fontes mais longas; a solicitação de geração ainda permite no máximo 10 referências de áudio totalizando no máximo 30 segundos.

Erros de revisão de vídeo: a aceitação de uma solicitação de revisão não estabelece que um vídeo é utilizável. Uma revisão pode falhar com FormatUnsupported ou Unsupported media format. Verifique o contêiner real, codec, dimensões, taxa de quadros, faixa de áudio e acessibilidade do URL; referencie um vídeo da biblioteca somente após ele se tornar Active. Vídeos de pessoa real exigem aprovação de revisão antes da geração.

Use um URL HTTP(S) que baixe o arquivo diretamente sem login, cookies, cabeçalhos de autorização extras ou restrições anti-hotlink. Mantenha URLs assinados válidos durante a recuperação e revisão, e mantenha seu conteúdo inalterado. HTML de página de compartilhamento, links expirados, endereços de rede privada, codecs quebrados ou extensões de arquivo enganosas podem causar rejeição. Carregue vídeo e áudio em seu próprio armazenamento de arquivos e envie seus URLs diretos; o endpoint de upload de arquivo de imagem abaixo não aceita vídeo ou áudio.

Etapa 1: carregar um arquivo de imagem local

Envie dados de formulário multipart para POST https://apimaster.ai/v1/uploads/images com um campo chamado file. Não defina manualmente um tipo de conteúdo JSON: seu cliente HTTP deve fornecer o limite multipart.

curl --fail-with-body -sS "https://apimaster.ai/v1/uploads/images" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./reference.png"

Exemplo de resposta:

{
  "url": "https://apimaster.ai/imgs/media_upload_example.png",
  "filename": "reference.png",
  "content_type": "image/png",
  "bytes": 123456,
  "created_at": 1790812800
}

Este endpoint aceita apenas JPEG, PNG, GIF e WebP, com um tamanho máximo de arquivo de 20 MiB (20 × 1024 × 1024 bytes). Ele verifica o formato de imagem detectado e as dimensões legíveis da imagem; um upload bem-sucedido não valida todos os requisitos do Seedance ou aprova o conteúdo. Imagens maiores que este limite de upload, e formatos compatíveis com a biblioteca ausentes desta lista, precisam do seu próprio armazenamento de arquivos público.

O URL retornado usa o domínio do APIMaster e é publicamente legível por qualquer pessoa que conheça o URL. Ele é destinado a entrada de mídia da API, em vez de armazenamento arquivístico permanente; mantenha seu arquivo original e não assuma um período de retenção garantido. Não carregue conteúdo confidencial que deva exigir autenticação de download. Reutilize o URL na próxima etapa, ou diretamente em uma solicitação de geração quando a revisão da biblioteca não for necessária.

Etapa 2: enviar materiais para revisão

Envie JSON para POST https://apimaster.ai/v1/seedance2/private-avatar/assets. Defina um novo group ou um group_id existente do APIMaster, nunca ambos. Omitir ambos cria um novo grupo automaticamente.

curl --fail-with-body -sS "https://apimaster.ai/v1/seedance2/private-avatar/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "group": {"name": "My reference materials", "description": "Approved generation references"},
    "project_name": "default",
    "asset_type": "Image",
    "assets": [
      {"url": "https://apimaster.ai/imgs/media_upload_example.png", "name": "reference-portrait"}
    ]
  }'

Para vídeo ou áudio, use asset_type: "Video" ou asset_type: "Audio" com URLs diretos na mesma estrutura assets. Não misture tipos dentro de um único envio.

Campo	Tipo	Requisito e comportamento
`model`	string	Use `seedance-2.5` para este guia; padrão é `seedance-2.0`
`group`	objeto	Novo grupo opcional: `name` até 255 caracteres, `description` até 4000 caracteres
`group_id`	string	ID de grupo existente opcional retornado pelo APIMaster; deve pertencer à sua conta
`project_name`	string	Opcional; atualmente apenas `default` é suportado
`asset_type`	string	`Image`, `Video` ou `Audio` sensível a maiúsculas/minúsculas; padrão `Image`
`assets`	objeto[]	Array obrigatório contendo `1`–`20` materiais do tipo selecionado
`assets[].url`	string	URL de arquivo HTTP(S) público obrigatório; máximo de 8192 caracteres
`assets[].name`	string	Nome de exibição opcional, até 255 caracteres; um nome automático é usado se omitido

Exemplo de resposta aceita:

{
  "code": 200,
  "data": {
    "id": "asset_task_example",
    "object": "seedance.avatar.asset.task",
    "model": "seedance-2.5",
    "status": "processing",
    "progress": 0,
    "group_id": "group_example"
  }
}

Salve data.id como o ID da tarefa de revisão e data.group_id para envios posteriores. Uma resposta HTTP de sucesso apenas confirma a aceitação. Não construa um ID de ativo a partir de um nome de arquivo ou do ID da tarefa.

Etapa 3: consultar a tarefa de revisão e selecionar ativos aprovados

Consulte GET https://apimaster.ai/v1/tasks/{review_task_id} a cada 5–10 segundos até que data.status se torne completed ou failed. Este endpoint é para a tarefa de revisão de material; use os endpoints de vídeo documentados em outro lugar desta página para geração de vídeo.

curl --fail-with-body -sS "https://apimaster.ai/v1/tasks/asset_task_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemplo de resposta concluída; campos de timestamp e URL de origem são omitidos aqui por brevidade:

{
  "code": 200,
  "data": {
    "id": "asset_task_example",
    "object": "seedance.avatar.asset.task",
    "model": "seedance-2.5",
    "status": "completed",
    "progress": 100,
    "group_id": "group_example",
    "result": {
      "assets": [{"id": "asset_example", "asset_id": "asset_example", "asset_url": "asset://asset_example", "name": "reference-portrait", "asset_type": "Image", "group_id": "group_example", "status": "Active"}],
      "usable_assets": [{"id": "asset_example", "asset_id": "asset_example", "asset_url": "asset://asset_example", "name": "reference-portrait", "asset_type": "Image", "group_id": "group_example", "status": "Active"}],
      "failed_assets": []
    }
  }
}

Os estados da tarefa de revisão são processing, completed e failed. Os estados do material são Pending, Active e Failed; apenas materiais Active podem ser referenciados. Use o asset_url retornado inalterado. Ele identifica um material da biblioteca aprovado e não é um URL de download HTTP.

Um lote pode ter sucesso parcial. Um material rejeitado pode fazer com que a tarefa de revisão geral fique failed enquanto outros materiais já estão Active. Inspecione result.usable_assets e result.failed_assets, em vez de descartar todos os itens quando a tarefa falhar. Uma falha antes que os resultados do material estejam disponíveis pode retornar uma mensagem segura error sem um resultado. Corrija e reenvie apenas as entradas rejeitadas; evite repetir as aceitas.

Consulte a tarefa de revisão antes de confiar na lista da biblioteca: listas não consultam automaticamente tarefas de revisão pendentes. Consultas de tarefa e detalhes de ativo retornam os IDs públicos de material usados por solicitações subsequentes.

Etapa 4: gerar com um material aprovado

Use um asset_url aprovado em image_urls, image_with_roles[].url, video_urls ou audio_urls, correspondendo ao tipo de material. Este exemplo de primeiro quadro usa a imagem aprovada:

{
  "model": "seedance-2.5",
  "prompt": "The person slowly turns toward the camera, natural lighting, gentle camera movement.",
  "image_with_roles": [{"url": "asset://asset_example", "role": "first_frame"}],
  "aspect_ratio": "adaptive",
  "duration": 5,
  "resolution": "720p",
  "generate_audio": false
}

Envie este JSON para POST https://apimaster.ai/v1/videos/generations, então consulte a tarefa de vídeo retornada conforme descrito abaixo. Um ativo aprovado sob uma conta não pode ser usado por outra conta. Mantenha os IDs retornados pelo APIMaster; IDs copiados de outro serviço não funcionarão. Materiais combinados em uma solicitação devem vir de um contexto de biblioteca compatível; se indisponível, crie-os juntos no mesmo grupo do APIMaster e tente novamente após a revisão. Excluir um material impede que solicitações futuras o referenciem.

Se uma solicitação usando ativos da biblioteca não puder ser enviada, verifique seu status e seu histórico de tarefas antes de enviar novamente. Evite solicitações de geração duplicadas imediatas, especialmente após um timeout de rede.

Listar, inspecionar, renomear e excluir materiais

Todos os endpoints exigem uma chave de API do APIMaster. A biblioteca é escopada para sua conta, então chaves pertencentes à mesma conta podem acessar seus recursos; recursos de outra conta retornam HTTP 404. Operações de lista retornam apenas materiais e grupos da sua conta.

Método	Endpoint	Propósito
`POST`	`https://apimaster.ai/v1/seedance2/private-avatar/groups`	Criar um grupo usando `model`, `name` e opcional `description`
`GET`	`https://apimaster.ai/v1/seedance2/private-avatar/groups`	Listar seus grupos
`GET`	`https://apimaster.ai/v1/seedance2/private-avatar/groups/{group_id}`	Inspecionar um grupo
`PATCH`	`https://apimaster.ai/v1/seedance2/private-avatar/groups/{group_id}`	Atualizar `name` e/ou `description`
`DELETE`	`https://apimaster.ai/v1/seedance2/private-avatar/groups/{group_id}`	Excluir um grupo vazio
`POST`	`https://apimaster.ai/v1/seedance2/private-avatar/assets`	Enviar um lote de revisão
`GET`	`https://apimaster.ai/v1/seedance2/private-avatar/assets`	Listar seus materiais
`GET`	`https://apimaster.ai/v1/seedance2/private-avatar/assets/{asset_id}`	Inspecionar um material e atualizar seu status de revisão
`PATCH`	`https://apimaster.ai/v1/seedance2/private-avatar/assets/{asset_id}`	Atualizar o `name` de exibição
`DELETE`	`https://apimaster.ai/v1/seedance2/private-avatar/assets/{asset_id}`	Excluir um material
`GET`	`https://apimaster.ai/v1/tasks/{review_task_id}`	Consultar uma tarefa de revisão

Consultas de lista aceitam page (padrão 1) e limit (padrão 20, intervalo 1–100). A lista de materiais também aceita seu group_id e um filtro status sensível a maiúsculas/minúsculas. Sua resposta é {"code":200,"data":{"items":[],"total":0,"page":1,"limit":20}}; os itens usam os mesmos campos públicos dos detalhes de material/grupo. Resultados de lista não incluem recursos criados fora do APIMaster.

Exemplos:

# List approved materials in a group.
curl --fail-with-body -sS "https://apimaster.ai/v1/seedance2/private-avatar/assets?group_id=group_example&status=Active&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Rename one material without changing the source file.
curl --fail-with-body -sS -X PATCH "https://apimaster.ai/v1/seedance2/private-avatar/assets/asset_example" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"approved-reference"}'

# Delete a material before deleting its group.
curl --fail-with-body -sS -X DELETE "https://apimaster.ai/v1/seedance2/private-avatar/assets/asset_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

A criação de grupo usa como padrão seedance-2.5; forneça model explicitamente para clareza. Mudanças no nome de exibição não substituem o arquivo do material nem repetem a revisão. Para substituir mídia, envie uma nova revisão. Materiais pendentes que ainda não têm uma revisão concluída não podem ser renomeados ou excluídos e retornam HTTP 409. Exclua todos os materiais em um grupo antes de excluir o grupo; grupos não vazios retornam HTTP 409. Uma exclusão bem-sucedida retorna {"code":200,"data":{"id":"asset_example","deleted":true}} (uma exclusão de grupo retorna seu ID de grupo).

Cobranças, limites de taxa e erros

Upload de arquivo de imagem, revisão de material e operações CRUD da biblioteca não têm cobrança de geração e não criam registros de faturamento de uso de vídeo. Geração de vídeo usando materiais aprovados é cobrada normalmente de acordo com o modelo selecionado e referências. Operações gratuitas da biblioteca ainda exigem uma chave autorizada válida e permanecem sujeitas aos limites de taxa de chave de API/modelo. Endpoints de upload e criação limitam adicionalmente solicitações por IP; espaçe solicitações em vez de enviar grandes rajadas.

Status HTTP	Significado	Ação sugerida
`400`	JSON inválido, campos, URL, dados de imagem, tipo ou tamanho de lote	Verifique o esquema e as propriedades reais do arquivo
`401` / `403`	Chave ausente/inválida ou permissão de modelo insuficiente	Verifique sua chave APIMaster e modelos permitidos
`404`	Material/grupo/tarefa de revisão desconhecido, excluído ou inacessível	Use IDs retornados para a mesma conta
`400` / `409`	Material ainda não pronto, contexto de material incompatível ou grupo não vazio	Conclua a revisão, use um grupo compatível ou remova membros do grupo
`413`	Upload de imagem excede o limite de tamanho de arquivo/corpo	Reduza o tamanho do arquivo ou use seu próprio armazenamento público
`429`	Limite de taxa de solicitação atingido	Reduza a concorrência e tente novamente consultas com backoff
`502` / `503`	Serviço de revisão indisponível ou resposta inválida	Tente novamente consultas primeiro; retenha IDs de tarefa e material existentes

Uma tarefa de revisão pode retornar HTTP 200 com data.status: "failed"; inspecione o estado da tarefa e sua mensagem de erro segura, em vez de confiar apenas no código HTTP. Leia a explicação retornada e mantenha o ID público da tarefa de revisão para suporte.

FAQ da biblioteca de mídia

Quanto tempo leva a revisão? Consulte a cada 5–10 segundos. A duração varia por material e carga de trabalho do serviço; revisão de vídeo e de pessoa real pode levar mais tempo que revisão de imagem. Um envio aceito não é aprovação.
E se a revisão falhar sem explicação? Inspecione a tarefa de revisão e failed_assets; mantenha seus IDs públicos de tarefa/ativo para suporte. Verifique formato e acessibilidade do URL antes de enviar material corrigido. Uma consulta não reinicia uma revisão falha.
Preciso carregar novamente para 2.0 versus 2.5? Um ativo APIMaster aprovado pode ser reutilizado quando sua chave tem acesso ao modelo de destino e o material atende aos limites desse modelo. IDs entre plataformas não podem ser reutilizados.
Um lote pode ter sucesso parcial? Sim. Reutilize apenas usable_assets cujo status seja Active; corrija itens rejeitados individualmente.
O que significa um erro de material síncrono? HTTP 400 rejeita entrada inválida. invalid_asset_material pode identificar assets[0], assets[1] e assim por diante; índices começam em zero. Corrija o formato ou duração do item indicado antes de enviar novamente.

{
  "error": {
    "message": "invalid_asset_material: assets[0] video duration must be from 2 to 30 seconds",
    "type": "media_library_error"
  }
}

Modo de pré-visualização: rascunho 480p para final 1080p

Uma pré-visualização é uma geração normal faturada com draft: true. É válida para upgrades por 7 dias a partir do horário de criação da tarefa de pré-visualização. Cada upgrade é uma tarefa e cobrança independente; a mesma pré-visualização bem-sucedida e não expirada pode ser atualizada várias vezes.

Passo 1: gerar e consultar uma pré-visualização

curl --fail-with-body -sS "https://apimaster.ai/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.5","prompt":"A colorful abstract pattern gently moves.","draft":true,"duration":5,"return_last_frame":true}'

A resolução omitida torna-se 480p. Enviar 720p ou 1080p com draft: true retorna 400. Consulte o ID público retornado através de /v1/videos/{task_id} ou /v1/video/generations/{task_id} e aguarde o sucesso antes de fazer o upgrade. Outros parâmetros de geração e limites de mídia aplicam-se normalmente.

Passo 2: criar um vídeo final a partir da pré-visualização

curl --fail-with-body -sS "https://apimaster.ai/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.5","draft_task_id":"task_preview_example","output_format":"mp4","return_last_frame":true,"watermark":false}'

A resposta contém um ID de tarefa pública novo. A resolução omitida torna-se 1080p; todos os outros valores de resolução retornam 400. Use uma chave de API pertencente à conta da pré-visualização. Uma tarefa ausente, estrangeira, que não seja pré-visualização, incompleta, expirada ou de modelo diferente é rejeitada de forma síncrona com 400, sem criar uma tarefa ou cobrar uma reserva.

Se a pré-visualização estiver temporariamente indisponível, tente novamente mais tarde com o mesmo draft_task_id. Não o substitua pelo ID de outra plataforma. Um upgrade de pré-visualização não pode ser redirecionado para um contexto de geração diferente.

Campos herdados e alterações permitidas

Não reenvie campos herdados, mesmo quando seu valor for idêntico, false, 0 ou null:

prompt, image_urls, image_with_roles, video_urls, audio_urls, duration, size, aspect_ratio, ratio, seed, generate_audio, audio, omni_reference_task_type, generation_type, camerafixed, web_search, tools.

A mesma restrição aplica-se aos apelidos de entrada do APIMaster e ao wrapper legado: seconds, images, image, input_reference, first_frame_image, last_frame_image, video_list, negative_prompt, metadata.

Além de model, draft_task_id e da resolução fixa 1080p, os campos ajustáveis são apenas output_format, return_last_frame e watermark. Valores omitidos usam mp4, false e false, respectivamente. Os flags de último quadro e marca d'água não são herdados da pré-visualização. Não combine draft_task_id com draft: true. Tanto a criação da pré-visualização quanto o upgrade rejeitam service_tier.

Reservas de pré-visualização e vídeo final

Duração da pré-visualização	Reserva da pré-visualização	Reserva do vídeo final
`4`–`30` segundos explícitos	Duração especificada em 480p; trabalho de vídeo de referência incluído normalmente	Mesma duração no nível 1080p sem entrada de vídeo
`-1`, incluindo duração omitida em `edit`	Até o máximo de 30 segundos	Até 30 segundos em 1080p sem entrada de vídeo
Outra duração omitida	5 segundos em 480p	5 segundos em 1080p sem entrada de vídeo

O trabalho de pré-visualização segue o preço comum de 480p; a duração do vídeo de referência conta normalmente, com a duração faturada combinada limitada a 30 segundos. O trabalho do vídeo final usa o nível 1080p sem entrada de vídeo, excluindo a duração do vídeo de referência da pré-visualização. O sucesso liquida o uso real e reembolsa ou cobra a diferença; a falha reembolsa a reserva total. Os preços vêm do seu cartão de modelo e registros de carteira.

Moderação opcional de texto e imagem

nsfw_check tem como padrão false. No Seedance 2.0 e 2.5, defini-lo como true ativa verificações pré-submissão de prompt, negative_prompt e entradas de imagem: image_urls, image_with_roles[].url, apelidos de primeiro/último quadro e ativos de biblioteca do tipo imagem. URLs de geração não aceitam imagens base64; faça upload de um arquivo de imagem primeiro. Vídeo, áudio e ativos do tipo vídeo/áudio estão fora desta verificação de texto/imagem.

Uma violação detectada retorna HTTP 400 com a seguinte estrutura de resposta; nenhuma tarefa de vídeo ou reserva de geração é criada:

{
  "code": "nsfw_content_detected",
  "message": "Your request was rejected by content moderation (`nsfw_check` is enabled). Flagged categories: sexual.",
  "data": null
}

Esta verificação opcional não tem custo de geração e não é uma garantia absoluta de segurança de conteúdo. Uma falha na verificação ou a ausência de detecção não estabelece que uma geração posterior será aprovada. Use apenas conteúdo autorizado e em conformidade, independentemente do flag.

Consultar status e baixar

A mesma tarefa pode ser lida através de qualquer um dos formatos de consulta. Faça polling em um intervalo moderado, como a cada 5–10 segundos, e pare em um estado terminal. O tempo de geração depende da carga de trabalho, duração do clipe, resolução e referências; não trate uma tarefa lenta como motivo para criar tarefas duplicadas.

curl --fail-with-body -sS "https://apimaster.ai/v1/video/generations/task_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl --fail-with-body -sS "https://apimaster.ai/v1/videos/task_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl --fail-with-body -L "https://apimaster.ai/v1/videos/task_example/content" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o output.mp4

Respostas de conclusão

Formato de compatibilidade, GET /v1/video/generations/{task_id}:

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_example",
    "status": "succeeded",
    "url": "https://apimaster.ai/v1/videos/task_example/content",
    "format": "mp4",
    "error": null,
    "metadata": null,
    "usage": {"completion_tokens": 108900},
    "actual_time": 160,
    "last_frame_url": "https://apimaster.ai/v1/videos/task_example/last-frame"
  }
}

Formato estilo OpenAI, GET /v1/videos/{task_id}:

{
  "id": "task_example",
  "object": "video",
  "model": "seedance-2.5",
  "status": "completed",
  "progress": "100%",
  "url": "https://apimaster.ai/v1/videos/task_example/content",
  "usage": {"completion_tokens": 108900},
  "actual_time": 160,
  "last_frame_url": "https://apimaster.ai/v1/videos/task_example/last-frame"
}

Significado	Localização compatibilidade	Localização estilo OpenAI
ID público da tarefa	`data.task_id`	`id`
Aguardando	`data.status: queued`	`status: queued`
Gerando	`data.status: processing`	`status: in_progress`
Sucesso	`data.status: succeeded`	`status: completed`
Falha	`data.status: failed`	`status: failed`
URL de download do vídeo	`data.url`	`url`
Tokens de conclusão	`data.usage.completion_tokens`	`usage.completion_tokens`
Segundos decorridos	`data.actual_time`	`actual_time`
URL da imagem do último quadro	`data.last_frame_url`	`last_frame_url`
Explicação da falha	`data.error.message`	`error.message`
Contêiner de saída	`data.format`	Use o `output_format` solicitado ao salvar
Metadados legados	`data.metadata`, atualmente `null`	Não utilizado

actual_time é o tempo de conclusão menos o tempo de envio, em segundos, incluindo o tempo de espera; não é a duração do vídeo. usage.completion_tokens é a estatística de geração registrada e corresponde à contagem de tokens do log de consumo. A liquidação monetária do APIMaster usa a duração do vídeo e seu nível aplicável; a estatística de tokens não é uma fórmula de preço monetário. As respostas não contêm campos de valor; use os registros de consumo da sua carteira para liquidação.

O uso pode estar ausente logo após a conclusão; consulte novamente mais tarde. last_frame_url é retornado apenas após o sucesso, quando você solicitou return_last_frame: true e um último quadro está disponível. O campo é omitido, em vez de definido como null, quando não solicitado, ainda pendente ou com falha. Atualizações de visualização usam sua própria flag.

Resposta de falha

Uma tarefa com falha ainda é consultada com HTTP 200. A resposta estilo OpenAI pode conter:

{
  "id": "task_example",
  "object": "video",
  "model": "seedance-2.5",
  "status": "failed",
  "progress": "100%",
  "error": {"code": "task_failed", "message": "[upstream_error] Unsupported media format."}
}

O formato de compatibilidade coloca a explicação em data.error.message. Tarefas com falha não têm download de vídeo ou do último quadro. Preserve o ID público da tarefa e a explicação para suporte.

Baixar vídeo e último quadro

Envie Authorization: Bearer YOUR_API_KEY ao baixar qualquer URL. Use uma chave pertencente à conta da tarefa. O conteúdo do vídeo é MP4 ou MOV conforme a solicitação; salve MOV com uma extensão .mov. Um último quadro é uma imagem, então use o tipo de conteúdo retornado ao selecionar sua extensão.

curl --fail-with-body -L "https://apimaster.ai/v1/videos/task_example/last-frame" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o last-frame.jpg

Baixe e salve arquivos bem-sucedidos prontamente. A disponibilidade não é indefinida; reter um ID de tarefa não garante que seu arquivo de saída permaneça disponível para download. Se o arquivo não estiver mais disponível, o download retorna HTTP 410 com error.message: "Media has expired or is no longer available". Um último quadro indisponível ou não solicitado retorna HTTP 404. Autenticação de download ausente retorna HTTP 401.

Python: enviar, fazer polling e salvar

import os
import time
import requests

base = "https://apimaster.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['APIMASTER_API_KEY']}"}
payload = {
    "model": "seedance-2.5",
    "prompt": "A lighthouse above a calm sea, slow camera push-in, no text.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "adaptive",
    "generate_audio": True,
    "watermark": False,
    "return_last_frame": True,
}
response = requests.post(f"{base}/videos/generations", headers=headers,
                         json=payload, timeout=60)
response.raise_for_status()
created = response.json()
data = created.get("data")
if isinstance(data, list) and data:
    task_id = data[0].get("task_id")
else:
    item = data if isinstance(data, dict) else created
    task_id = item.get("task_id") or item.get("id")
if not task_id:
    raise RuntimeError("No task ID returned; inspect the submission response.")
print("task_id:", task_id)

# Example client timeout, not a promised generation deadline.
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    response = requests.get(f"{base}/videos/{task_id}", headers=headers, timeout=60)
    response.raise_for_status()
    task = response.json()
    state = task.get("status")
    if state == "failed":
        error = task.get("error") or {}
        raise RuntimeError(error.get("message", "Video generation failed."))
    if state == "completed":
        result = requests.get(f"{base}/videos/{task_id}/content", headers=headers,
                              timeout=120, stream=True)
        result.raise_for_status()
        with open("output.mp4", "wb") as output:
            for chunk in result.iter_content(1024 * 1024):
                if chunk:
                    output.write(chunk)
        print("Saved output.mp4")
        print("usage:", task.get("usage"), "actual_time:", task.get("actual_time"))
        if task.get("last_frame_url"):
            frame = requests.get(task["last_frame_url"], headers=headers, timeout=60)
            frame.raise_for_status()
            with open("last-frame.jpg", "wb") as image:
                image.write(frame.content)
            print("Saved last-frame.jpg")
        break
    time.sleep(5)
else:
    raise TimeoutError(f"Task {task_id} is still pending; keep this ID and query it later.")

Um timeout de conexão durante o envio deixa o resultado incerto: mantenha qualquer ID de tarefa retornado e verifique o histórico de suas tarefas antes de enviar novamente. Um timeout de polling não cancela uma tarefa. Evite tentativas automáticas de um envio faturável quando você não sabe se ele foi aceito.

Cobrança, reservas e reembolsos

A cobrança usa duração em segundos e depende da resolução, tipo de mídia de entrada e o preço aplicável da sua conta. Áudio gerado versus silencioso não seleciona um nível de preço separado na configuração atual do Seedance 2.5. Verifique o cartão do modelo e o preço de vídeo/mídia da carteira antes do envio; esta página não codifica um preço em mudança.

O envio reserva um valor estimado. Duração ordinária omitida reserva 5 segundos. Para duration: -1, a estimativa usa o máximo de 30 segundos, portanto, saldo suficiente é necessário mesmo que o resultado seja mais curto.
Com vídeo de referência, o trabalho faturável pode incluir a duração do vídeo de referência mais a duração do vídeo gerado. Uma saída de 5 segundos não é necessariamente faturada como apenas 5 segundos de trabalho.
Após geração bem-sucedida, o uso final medido pode produzir uma cobrança adicional ou um reembolso da diferença. Use os registros finais da carteira para confirmar a liquidação.
Tarefas com falha reembolsam a reserva de geração. Uma tarefa com falha ainda pode mostrar seu registro de consumo original junto com um reembolso correspondente; conte ambos ao verificar o valor líquido cobrado.
Corrigir uma solicitação inválida requer um novo envio. Um ID de tarefa com falha existente não pode ser reiniciado continuando a consultá-lo.

Exemplos em JavaScript, Go, Java e PHP

Estes exemplos enviam uma tarefa de texto para vídeo e imprimem sua resposta. Salve data[0].task_id, então use o fluxo de consulta/download acima. Leia sua chave do ambiente do servidor.

JavaScript (Node.js)

const response = await fetch("https://apimaster.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.APIMASTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2.5", prompt: "A lighthouse at sunrise, slow camera push-in.",
    duration: 5, resolution: "720p", aspect_ratio: "adaptive",
    generate_audio: true, watermark: false, output_format: "mp4",
  }),
});
const body = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${body}`);
console.log(JSON.parse(body));

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "time"
)

func main() {
    payload, err := json.Marshal(map[string]any{
        "model": "seedance-2.5", "prompt": "A lighthouse at sunrise, slow camera push-in.",
        "duration": 5, "resolution": "720p", "aspect_ratio": "adaptive",
        "generate_audio": true, "watermark": false, "output_format": "mp4",
    })
    if err != nil { panic(err) }
    req, err := http.NewRequest("POST", "https://apimaster.ai/v1/videos/generations", bytes.NewReader(payload))
    if err != nil { panic(err) }
    req.Header.Set("Authorization", "Bearer " + os.Getenv("APIMASTER_API_KEY"))
    req.Header.Set("Content-Type", "application/json")
    response, err := (&http.Client{Timeout: 60 * time.Second}).Do(req)
    if err != nil { panic(err) }
    defer response.Body.Close()
    body, err := io.ReadAll(response.Body)
    if err != nil { panic(err) }
    if response.StatusCode >= 400 { panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, body)) }
    fmt.Println(string(body))
}

Java (JDK 11+)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class SeedanceExample {
    public static void main(String[] args) throws Exception {
        String json = "{\"model\":\"seedance-2.5\",\"prompt\":\"A lighthouse at sunrise.\","
            + "\"duration\":5,\"resolution\":\"720p\",\"aspect_ratio\":\"adaptive\","
            + "\"generate_audio\":true,\"watermark\":false,\"output_format\":\"mp4\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://apimaster.ai/v1/videos/generations"))
            .timeout(Duration.ofSeconds(60))
            .header("Authorization", "Bearer " + System.getenv("APIMASTER_API_KEY"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json)).build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new RuntimeException("HTTP " + response.statusCode() + ": " + response.body());
        }
        System.out.println(response.body());
    }
}

PHP

<?php
$payload = [
    'model' => 'seedance-2.5', 'prompt' => 'A lighthouse at sunrise, slow camera push-in.',
    'duration' => 5, 'resolution' => '720p', 'aspect_ratio' => 'adaptive',
    'generate_audio' => true, 'watermark' => false, 'output_format' => 'mp4',
];
$handle = curl_init('https://apimaster.ai/v1/videos/generations');
curl_setopt_array($handle, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('APIMASTER_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
]);
$body = curl_exec($handle);
if ($body === false) { throw new RuntimeException(curl_error($handle)); }
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);
if ($status >= 400) { throw new RuntimeException("HTTP $status: $body"); }
print_r(json_decode($body, true, 512, JSON_THROW_ON_ERROR));

Migração de outra integração Seedance 2.5

Defina sua URL base como https://apimaster.ai/v1 e envie para POST /v1/videos/generations. Use as definições de campo e padrões do APIMaster desta página; mantenha duração, proporção e áudio explícitos ao migrar uma integração existente.

Use GET /v1/video/generations/{task_id} ou GET /v1/videos/{task_id} para vídeos. /v1/tasks/{id} também atende tarefas de revisão de mídia; para um ID de vídeo do APIMaster, ele retorna a resposta de vídeo de compatibilidade. Prefira os dois endpoints dedicados a vídeo para manter o tratamento de vídeo e revisão claros.

Outra integração	Compatibilidade APIMaster	Estilo OpenAI APIMaster
`pending`	`data.status: queued`	`status: queued`
`processing`	`data.status: processing`	`status: in_progress`
`completed`	`data.status: succeeded`	`status: completed`
`failed`	`data.status: failed`	`status: failed`
`data.result.videos[].url[0]`	`data.url`	`url`
Resultado do último quadro	`data.last_frame_url`	`last_frame_url`
Uso da geração	`data.usage.completion_tokens`	`usage.completion_tokens`
Tempo decorrido	`data.actual_time`	`actual_time`

Baixe URLs de vídeo e do último quadro com a chave Bearer da sua conta. O APIMaster não retorna campos de quantidade; use os registros de consumo da carteira. IDs de tarefa, IDs asset:// e draft_task_id são específicos do APIMaster e não podem ser copiados entre plataformas. Envie e revise seus materiais novamente no APIMaster. Salve as saídas prontamente em vez de presumir que o período de retenção de outro serviço se aplica.

Diferenças entre Seedance 2.0 e 2.5

Use a documentação específica do modelo ao alterar modelos. Limites não são inferidos a partir do número de versão de um modelo.

Capacidade	Seedance 2.0	Seedance 2.5
Modelo público	`seedance-2.0`	`seedance-2.5`
Duração padrão	`4` segundos	`5` segundos; edição padrão para `-1`
Duração da geração	`4`–`15` s	`4`–`30` segundos, ou `-1`
Resolução	`480p`, `720p`, `1080p`, `4K`	`480p`, `720p`, `1080p`
Contagem de imagens/vídeos/áudio e duração total	Siga os limites de mídia do modelo 2.0	`30` imagens, `10` vídeos totalizando no máximo `30` segundos, `10` clipes de áudio totalizando no máximo `30` segundos
Referência de áudio puro	Siga o modo documentado do modelo 2.0	Suportado
Formato de saída	`mp4`, `mov`	`mp4`, `mov`
Marca d'água	Siga as opções documentadas do modelo 2.0	`false` por padrão
Pré-visualização e atualização	Não suportado por este fluxo de trabalho	Prévia 480p → final 1080p; válido por 7 dias
Padrão de ingestão de vídeo na biblioteca de mídia	Limite individual de vídeo `15` segundos	Limite individual de vídeo `30` segundos quando explicitamente selecionado
Ingestão de áudio na biblioteca de mídia	`2`–`15` segundos	`2`–`15` segundos
Referências `asset://` aprovadas	Ativos aprovados da mesma conta, sujeitos a permissões e limites do modelo	Mesma regra; IDs entre plataformas não são aceitos

Estruturas de resposta de erro

A validação de envio retorna HTTP 400 com um objeto error:

{
  "error": {
    "message": "draft resolution must be 480p",
    "type": "invalid_request_error"
  }
}

Alguns caminhos de rejeição de solicitação usam um envelope code / message / data, incluindo moderação e entradas de mídia inválidas:

{
  "code": "invalid_request",
  "message": "Invalid format for image_with_roles[0].url. Only http/https URLs or asset:// private asset URLs are supported.",
  "data": null
}

Autenticação de download ausente retorna HTTP 401:

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: request_example)",
    "type": "new_api_error"
  }
}

Lide com ambos os envelopes de erro: leia error.message quando presente, caso contrário message. Não exija um único campo de código de erro para detectar falha. Um HTTP 200 de consulta de vídeo ainda pode conter uma tarefa com falha.

Mensagem de envio	Significado
`unsupported seedance-2.5 resolution "4k"`	Use uma resolução suportada
`seedance-2.5 duration must be -1 or an integer from 4 to 30`	Duração fora do intervalo permitido
`first/last frame aspect_ratio must be adaptive`	Tarefa de quadro apenas com imagem usa uma proporção fixa
`edit requires at least one video_urls entry`	Fonte de edição ausente
`extend requires at least one video_urls entry`	Fonte de extensão ausente
`edit duration must be -1`	Duração de edição explícita não é automática
`draft resolution must be 480p`	Resolução de pré-visualização é inválida
`draft_task_id resolution must be 1080p`	Resolução de atualização é inválida
`draft and draft_task_id cannot be used together`	Campos de pré-visualização mutuamente exclusivos
`service_tier is not supported for draft tasks`	Campo de agendamento fornecido para pré-visualização ou atualização
`draft_task_id was not found in your account`	ID de pré-visualização ausente ou inacessível
`draft_task_id is not a draft task`	Tarefa comum fornecida como pré-visualização
`draft_task_id has not completed successfully`	Pré-visualização pendente ou com falha
`draft_task_id has expired; drafts are valid for 7 days`	Pré-visualização mais antiga que 7 dias
`draft_task_id model does not match`	Modelo de origem difere
`Draft is temporarily unavailable; retry with the same draft_task_id later`	Tente novamente mais tarde sem alterar o ID da pré-visualização
`prompt must not be supplied with draft_task_id`	Campo herdado reenviado; erros equivalentes nomeiam outros campos proibidos

Resolução de Problemas

Distinguir um erro de submissão síncrono de uma falha assíncrona: HTTP 200 com um ID de tarefa apenas confirma a aceitação. A tarefa pode posteriormente se tornar failed.

Erro ou sintoma	Causa provável	O que fazer
`ratio` inválido / a proporção do primeiro quadro deve seguir a imagem	Proporção fixa usada em uma tarefa de quadro	Defina `aspect_ratio: "adaptive"`; recorte/preencha a primeira imagem se uma proporção específica for necessária
`content[1]` inválido / formato de imagem inválido	Uma URL retorna HTML, um link expirado ou uma imagem não suportada/indecodificável	Abra a URL direta do arquivo sem login; converta para JPEG/PNG; verifique as dimensões e tente novamente com uma nova tarefa
Lado da imagem ou proporção fora do intervalo	Uma imagem é muito pequena/grande ou muito larga/alta	Cada lado `300`–`6000` pixels; largura/altura `0.4`–`2.5`
`InvalidParameter.TaskTypeConstraint`	Configurações de edição/extensão/quadro violam seu contrato específico da tarefa	Use `adaptive`; a edição também precisa de `duration: -1`
`InvalidParameter.TaskTypeMismatch`	O tipo de tarefa declarado e a intenção do prompt discordam	Reescreva o prompt e selecione um `omni_reference_task_type` correspondente
Conteúdo rejeitado / bloqueado por moderação	Entrada ou prompt viola as regras de conteúdo aplicáveis	Use mídia em conformidade e revise o prompt; não tente novamente o mesmo conteúdo rejeitado sem alterações
HTTP `400`	Prompt ausente, resolução/duração não suportada, mídia inválida ou aliases conflitantes	Verifique a solicitação nesta página antes de reenviar
HTTP `401` / `403`	Chave inválida ou autorização insuficiente	Use uma chave APIMaster ativa da conta que possui a tarefa
Saldo insuficiente, incluindo HTTP `402` ou um erro de saldo/cota	A reserva não pode ser coberta pelo saldo/disponibilidade da carteira/chave	Verifique o saldo da carteira, a disponibilidade da chave e a reserva de duração automática
HTTP `429`	Limite de taxa ou simultaneidade	Recue; reutilize o ID da tarefa existente ao consultar o status
HTTP `500` / `502` / tempo limite de rede	Falha temporária do serviço ou da conexão	Tente novamente as leituras com recuo; verifique o histórico de tarefas antes de tentar reenviar uma submissão
Tarefa concluída, mas o download falha	Download muito cedo, autenticação ausente ou saída indisponível	Consulte o estado novamente, envie a chave da mesma conta e mantenha o ID da tarefa para suporte

O log de tarefas do usuário e os detalhes do log de uso mostram explicações seguras para falhas. Ao entrar em contato com o suporte, inclua o ID público da tarefa, o horário aproximado da submissão, o modelo, a resolução, a duração e a mensagem de erro relevante. Nunca envie sua chave de API ou cabeçalho de autorização.

Relacionado: Visão geral da API de Vídeo · Seedance 2.0