Seedance 2.0 FastReferência da API

Tudo o que você precisa para chamar o Seedance 2.0 Fast por código: um início rápido em três etapas, cada campo com seus limites, a fórmula de preços, webhooks e idempotência. As ferramentas MCP rodam sobre a mesma API /v1; com login por MCP você usa o saldo criativo e, com uma chave de API, o saldo da API para desenvolvedores.

EndpointPOST /v1/videos/generationsVersão do modelodreamina-seedance-2-0-fast-260128OpenAPI llms.txt Para agentes de IA

Solicitar acesso à API

O acesso à API para desenvolvedores é por solicitação.

Início rápidoem três chamadas

Defina uma chave, envie a tarefa com um limite de preço e depois leia o resultado.

01
Defina sua chave
O acesso à API para desenvolvedores é por solicitação: peça no estúdio, em Chaves de API. A chave é exibida uma única vez, então guarde-a em uma variável de ambiente.
Shell
```
export API_KEY="sk_test_…"
```

Envie a tarefa

Envie o clipe por POST com um Idempotency-Key e um limite max_credits (ou um quote_id). Você recebe 202 e uma tarefa na fila na hora, e os créditos ficam reservados.

POST /videos/generations

curl https://api.pershot.app/v1/videos/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "Perfume mist in hard side light. Slow push-in, black background, grain.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "max_credits": 34
  }'

Você deve ver

{
  "id": "job_01J9ZK4T8W",
  "object": "job",
  "kind": "video",
  "status": "queued",
  "money_status": "reserved",
  "queue_position": 2,
  "requested_model": "seedance-2.0-fast",
  "credits_quoted": 34,
  "credits_charged": null
}

03
Leia o resultado
Consulte a tarefa por GET até o status ser succeeded. outputs[].url é assinada e expira após 24 horas, então baixe o que quiser guardar.
GET /jobs/{id}
```
curl https://api.pershot.app/v1/jobs/job_01J9ZK4T8W \
  -H "Authorization: Bearer $API_KEY"
```

Parâmetrose limites

Lidos do documento OpenAPI, que é gerado a partir dos mesmos esquemas que a API usa na validação. Campos desconhecidos são recusados.

Campos de requisição do Seedance 2.0 Fast
Campo	Tipo	Valores aceitos	Observações
`model`Obrigatório	string	seedance-2.0-fast · seedance-2.0-mini · auto	O ID do modelo.
`prompt`Obrigatório	string	2–2.000 caracteres	O que gerar: o assunto, a câmera e a luz.
`duration`Padrão: 5	integer	4–15	Duração da saída em segundos inteiros, até 15.
`resolution`Padrão: "720p"	string	480p · 720p	Resolução da saída. 480p para rascunhos, 720p para a entrega; cada uma é uma geração separada.
`aspect_ratio`Padrão: "16:9"	string	16:9 · 9:16 · 1:1	Formato do quadro.
`generate_audio`Padrão: true	boolean	–	Áudio nativo. O preço é o mesmo com o áudio ativado ou desativado.
`image_url`Opcional	string	URL https	Primeiro quadro do vídeo; a imagem de origem nos modelos de edição. Uma URL https pública ou a URL de um arquivo enviado.
`reference_image_urls`Opcional	string[]	Até 9 · URL https	Imagens de referência para assunto e estilo. Cite-as no prompt como @image1, @image2.
`seed`Opcional	integer	0–2.147.483.647	Aceita e ignorada: o Seedance 2.0 não usa semente.
`quote_id`Opcional	string	qt_…	Executa pelo preço de uma cotação de POST /v1/quotes, válida por 10 minutos.
`max_credits`Opcional	number	> 0	O máximo que esta tarefa pode custar. Acima disso, a tarefa é recusada, nunca cobrada.
`webhook_url`Opcional	string	URL https	Uma URL https que recebe os eventos da tarefa.
`end_user_id`Opcional	string	1–128 caracteres	Para contas de desenvolvedor aprovadas (o acesso é por solicitação): o seu próprio ID de usuário para esta solicitação, exibido nos dados de uso.
`project_id`Opcional	string	prj_…
`shot_id`Opcional	string	sht_…
`routing_preference`Opcional	string	stability · speed
`enhance`Opcional	object	–

Envie exatamente um entre quote_id e max_credits. Este endpoint recusa model "auto": para vídeo, chame primeiro POST /v1/auto/plan e depois envie o modelo escolhido com max_credits.

Taxa de requisições e simultaneidade: 60 requisições por minuto por chave e 3 tarefas ao mesmo tempo por conta, por padrão. Mais chaves não aumentam a simultaneidade.

Limites

Lidos da mesma tabela que a API usa nas verificações. Cada linha diz quem verifica o limite e o que acontece quando ele é ultrapassado.

Validado por nósVerificamos e respondemos 400 antes de qualquer cotação ou reserva.
Validado pelo fornecedorO fornecedor verifica. Uma tarefa recusada por ele falha, e nada é cobrado.
RecomendadoNinguém verifica. Ficar dentro do limite dá resultados melhores.

Limites para seedance-2.0-fast
Limite	Valor	Unidade	Quem verifica	Acima do limite
Requisição
Tamanho do prompt`prompt`	2 a 2.000	caracteres	Validado por nós	400 invalid_request no campo prompt, antes de qualquer cotação ou reserva.
Prompt em inglês`prompt`	até 1.000	palavras	Recomendado	Aceito. O modelo pode seguir com menos precisão um prompt mais longo.
Prompt em chinês`prompt`	até 500	caracteres chineses	Recomendado	Aceito. O modelo pode seguir com menos precisão um prompt mais longo.
Duração`duration`	4 a 15Padrão: 5	segundos	Validado por nós	400 invalid_request no campo duration. Só segundos inteiros.
Resolução`resolution`	480p, 720pPadrão: 720p	–	Validado por nós	400 invalid_request no campo resolution.
Proporção`aspect_ratio`	16:9, 9:16, 1:1Padrão: 16:9	–	Validado por nós	400 invalid_request no campo aspect_ratio.
Semente`seed`	Ignorado	–	Validado pelo fornecedor	Aceita e não enviada: o Seedance 2.0 não usa semente, então uma semente não reproduz um resultado.
Duração do vídeo de entrada`input_video_seconds`	2 a 15	segundos	Validado por nós	400 invalid_request em POST /v1/quotes. As gerações pela API não aceitam vídeo de entrada.
Imagens que você envia
Imagens de referência`reference_image_urls`	até 9	imagens	Validado por nós	400 invalid_request no campo reference_image_urls.
Primeiro quadro ou referências`reference_image_urls`	image_url ou reference_image_urls, não ambos	–	Validado por nós	400 invalid_request no campo reference_image_urls. O Seedance 2.0 executa um dos dois modos por tarefa.
Lado da imagem`image_urlreference_image_urls`	300 a 6.000	px por lado	Envios validados por nós	Envios: 400 invalid_request no campo image_url ou reference_image_urls.N, antes de qualquer cotação ou reserva. Outros links: o fornecedor recusa a tarefa, e nada é cobrado.
Proporção da imagem`image_urlreference_image_urls`	0,4 a 2,5	largura ÷ altura	Envios validados por nós	Envios: 400 invalid_request no campo image_url ou reference_image_urls.N, antes de qualquer cotação ou reserva. Outros links: o fornecedor recusa a tarefa, e nada é cobrado.
Tamanho do envio`file`	até 10	MB	Validado por nós	POST /v1/uploads responde 400 invalid_request no campo file.
Formatos de envio`file`	JPEG, PNG, WebP	–	Validado por nós	Identificado pelo próprio arquivo, não pelo nome dele. Qualquer outro: 400 invalid_request no campo file.
Tamanho da imagem via link`image_urlreference_image_urls`	até 30	MB	Validado pelo fornecedor	Para imagens hospedadas em outros sites. O fornecedor recusa a tarefa, e nada é cobrado.
Formatos da imagem via link`image_urlreference_image_urls`	JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF	–	Validado pelo fornecedor	Para imagens hospedadas em outros sites. O fornecedor recusa a tarefa, e nada é cobrado.
Saída
Pixels de saída	480p16:9864×4969:16496×8641:1640×640720p16:91280×7209:16720×12801:1960×960	px	Validado pelo fornecedor	Definidos pelo modelo para cada resolução e proporção.
Taxa de quadros	24	fps	Validado pelo fornecedor	A mesma em todos os vídeos.
Formato de saída	MP4	–	Validado pelo fornecedor	Todo vídeo é um MP4, com som quando generate_audio está ativado.
Links
Link de envio	7	dias	Validado por nós	Depois disso, o link responde 403. Envie o arquivo de novo.
Link do resultado	24	horas	Validado por nós	Depois disso, o link responde 403. Faça um novo GET da tarefa para obter um link novo. O arquivo em si é mantido por 12 meses (outputs_expire_at da tarefa indica a data), e por mais tempo se o resultado estiver salvo em Mídias ou for usado em um projeto.

Nunca buscamos imagens em outros sites, então, nesses links, quem verifica o tamanho é o fornecedor, e uma tarefa que ele recusa não é cobrada. Os mesmos limites também vêm em JSON: GET /v1/models retorna um objeto limits para cada modelo.

Limites de todos os modelos

Preçoscalculados às claras

Toda tarefa é cotada em créditos antes de rodar (US$ 1 = 100 créditos). A tarifa por segundo serve para planejar o orçamento; POST /v1/quotes retorna o valor exato.

créditos = ceil(preço de tabela da BytePlus × 0,55 × 100), onde preço de tabela = (s de entrada + s de saída) × largura × altura × 24 ÷ 1024 × tarifa de tabela

Preços do Seedance 2.0 Fast
Especificação	Por segundo (API)	5 s	10 s	15 s
480pSem entrada de vídeo	US$ 0,031Com vídeo de entrada: US$ 0,019/s≈ 322 s por US$ 10	16 cr≈ US$ 0,16	31 cr≈ US$ 0,31	47 cr≈ US$ 0,47
720pSem entrada de vídeo	US$ 0,067Com vídeo de entrada: US$ 0,040/s≈ 149 s por US$ 10	34 cr≈ US$ 0,34	67 cr≈ US$ 0,67	100 cr≈ US$ 1,00

Tarefas recusadas ou com falha não são cobradas.

Como os preços são calculados Compare com fal, Replicate e WaveSpeed

Webhookse idempotência

Novas tentativas nunca geram cobrança dupla, e você não precisa consultar a tarefa periodicamente.

Idempotência: Todo POST de geração exige um Idempotency-Key (de 1 a 255 caracteres ASCII visíveis). A mesma chave dentro de 24 horas retorna a mesma tarefa com HTTP 200, então uma nova tentativa após um timeout nunca cria nem cobra uma segunda tarefa.
Prompts recusados: Um prompt recusado pela pré-verificação (422 content_rejected) não cria nada, então a mesma chave pode ser usada de novo com um novo prompt.
Eventos: job.queuedjob.processingjob.succeededjob.failedjob.cancelled
Assinatura: X-Signature traz t, o tempo Unix, e v1, um HMAC-SHA256 de t, um ponto e o corpo bruto, com o seu segredo whsec_ como chave. Recuse carimbos de data/hora com mais de cinco minutos e elimine duplicatas pelo X-Event-Id.
Entrega: Um 2xx em até 10 segundos conta como entregue. Entregas com falha são repetidas após 1 min, 5 min, 30 min, 2 h e 6 h. Redirecionamentos não são seguidos.

Corpo do webhook

{
  "id": "evt_01J9ZKB1QX",
  "type": "job.succeeded",
  "created_at": "2026-09-29T14:02:31Z",
  "data": {
    "job": {
      "id": "job_01J9ZK4T8W",
      "object": "job",
      "kind": "video",
      "status": "succeeded",
      "money_status": "settled",
      "requested_model": "seedance-2.0-fast",
      "credits_charged": 34,
      "outputs": [
        {
          "kind": "video",
          "url": "https://…/job_01J9ZK4T8W.mp4?sig=…"
        }
      ]
    }
  }
}

Verificar X-Signature

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body exactly as received, before any JSON parsing.
export function verifyWebhook(header, rawBody, secret, toleranceSec = 300) {
  let t = null;
  const signatures = [];
  for (const item of (header ?? "").split(",")) {
    const [key, value] = item.split("=", 2);
    if (key === "t") t = Number(value);
    if (key === "v1") signatures.push(Buffer.from(value, "hex"));
  }
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return signatures.some((s) => s.length === expected.length && timingSafeEqual(s, expected));
}

// verifyWebhook(req.headers["x-signature"], rawBody, process.env.WEBHOOK_SECRET)
// Answer 2xx quickly, and skip an X-Event-Id you have already handled.

Errose o que fazer

Todo erro tem o mesmo formato: um objeto error com code, message, param e request_id. Os que você tem mais chance de encontrar:

Código	HTTP	O que fazer
`invalid_request`	400	Corrija o campo indicado em param.
`unauthorized`	401	Verifique a chave e o cabeçalho Bearer.
`insufficient_credits`	402	Recarregue e tente de novo com o mesmo Idempotency-Key.
`forbidden_model`	403	Adicione o modelo ou a ferramenta à lista de permissões da chave no estúdio, ou use outra chave. Ferramentas como Aprimorar precisam de uma entrada própria.
`quote_expired`	409	Peça uma nova cotação; as cotações valem por 10 minutos.
`price_changed`	409	O preço subiu acima do seu limite. Faça uma nova cotação ou aumente max_credits.
`content_rejected`	422	Nada foi cobrado. Altere o prompt ou as imagens.
`rate_limited`	429	Aguarde o Retry-After e tente de novo.
`upstream_unavailable`	503	O modelo está indisponível. Tente de novo mais tarde; uma tarefa que nunca começa não é cobrada.

Documento OpenAPI 3.1 llms.txt Documentação completa Vindo do fal, do Replicate ou do WaveSpeed

Defina sua chave

Envie a tarefa

Leia o resultado

Limites