Nesta página
Seedance 2.0 API
Crie tarefas de texto para vídeo e imagem para vídeo do Seedance 2.0 por uma API assíncrona. Esta primeira versão não expõe reference-to-video nem edição de vídeo.
REST API · v1 · Tarefas assíncronas
Envie sua primeira solicitação
Escolha text-to-video ou image-to-video, use uma chave idempotente e consulte o task ID.
- 1
Criar uma API Key
Gere uma chave na conta Imya.
- 2
Escolher o modo
Use apenas text-to-video ou image-to-video.
- 3
Obter o resultado
Consulte até concluir ou falhar.
Autenticação e idempotência
Envie a API Key como Bearer token e uma Idempotency-Key única em todo POST para repetir sem duplicar cobranças.
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEYCriar uma geração de vídeo
Cria uma tarefa assíncrona do Seedance e retorna credits_reserved em tempo real.
/v1/videos/generations# Text to video
curl https://imya.ai/v1/videos/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedance-t2v-order-001" \
-d '{
"model": "seedance-2.0",
"mode": "text-to-video",
"prompt": "A coastal train passing cliffs at sunrise",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": true
}'
# Image to video
curl https://imya.ai/v1/videos/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedance-i2v-order-001" \
-d '{
"model": "seedance-2.0",
"mode": "image-to-video",
"prompt": "Wind moves the fabric as the camera arcs right",
"image_url": "https://cdn.example.com/first-frame.jpg",
"duration": 8,
"resolution": "1080p",
"aspect_ratio": "16:9",
"generate_audio": true
}'Consultar uma tarefa
Retorna status, créditos finais, MP4 ou erro seguro. Consulte com intervalo mínimo de 5 segundos e baixe logo URLs temporárias.
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"Parâmetros
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| model | string | Sim | Use seedance-2.0. |
| mode | string | Sim | text-to-video ou image-to-video. |
| prompt | string | Sim | Instruções de geração com 3 a 5.000 caracteres. |
| image_url | string | Condicional | Primeiro quadro HTTPS público, obrigatório em image-to-video. |
| last_frame_url | string | Não | Último quadro HTTPS opcional para image-to-video. |
| duration | number | Não | Inteiro de 4 a 15 segundos. Padrão: 5. |
| resolution | string | Não | 480p, 720p ou 1080p. Padrão: 720p. |
| aspect_ratio | string | Não | auto, 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3 ou 21:9. O padrão é 16:9. |
| generate_audio | boolean | Não | Gera áudio. Padrão: true. |
| web_search | boolean | Não | Somente text-to-video. Padrão: false. |
Respostas
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "processing",
"model": "seedance-2.0",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 625
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "seedance-2.0",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:03:12.000Z",
"credits_reserved": 625,
"credits_used": 625,
"data": [
{
"url": "https://media.example.com/generated/example.mp4"
}
]
}Créditos em tempo real
O servidor calcula credits_reserved por modo, resolução, duração e plano. Áudio e busca web não mudam o cálculo atual. Use sempre o valor da resposta.
Status
pendingA tarefa foi aceita e aguarda início.
processingO modelo está gerando o vídeo.
succeededA geração terminou e data contém o MP4.
failedA geração falhou. Leia o erro seguro.
Erros
400Idempotency-Key ausente ou JSON inválido.
401API Key ausente ou inválida.
402Créditos insuficientes.
403Conta de API desativada.
404Tarefa inexistente ou de outra conta.
409Chave reutilizada com outro corpo.
413Corpo maior que 64 KiB.
415Content-Type deve ser application/json.
422Modo, prompt, imagem, duração, resolução ou proporção inválida.
429Limite de velocidade ou concorrência atingido.
5xxNão foi possível concluir ou enviar.
Contrato comum da API pública da Imya
Estas regras valem para todos os endpoints públicos de geração. Campos e preços específicos ficam na tabela do modelo.
Cobrança e repetição segura
Ao aceitar uma nova tarefa, os créditos exatos de credits_reserved são descontados atomicamente. Repetir a mesma Idempotency-Key e corpo retorna a tarefa original sem nova cobrança.
Prazo e reembolsos
Uma tarefa que não conclui em 30 minutos falha. Créditos elegíveis são devolvidos uma vez e mantêm a validade original.
Limites de velocidade e concorrência
Cada API Key aceita 120 solicitações por 60 segundos; uma conta executa até cinco tarefas de imagem ou três de vídeo. Respeite Retry-After no 429.
Consulta e propriedade
Consulte GET /v1/tasks/{id} com o id retornado e intervalo mínimo de 5 segundos. Só a conta criadora pode ler a tarefa; webhooks, SDK e envio batch não estão disponíveis.
Erros e segurança
Erros públicos removem credenciais, URLs internas e detalhes de infraestrutura. Um prompt inseguro pode ser rejeitado com prompt_blocked.
Retenção de imagens
Contas grátis mantêm imagens por 7 dias e contas pagas ativas ou Lifetime por até 30. Depois, status é failed e error.code é media_deleted.
Guia de integração em produção da Seedance 2.0 API
Projete a integração do Seedance 2.0 como um sistema de tarefas assíncronas recuperável, não como uma solicitação HTTP longa. Salve sempre o id da Imya e torne as repetições determinísticas.
Escolher parâmetros do contrato
Valide cada solicitação com a tabela desta página. Comece com a configuração mínima e aumente qualidade, tamanho, duração ou referências somente quando necessário.
Permita apenas combinações documentadas de duração, resolução, proporção, áudio e mídia.
Projetar um fluxo assíncrono recuperável
Envie a tarefa de vídeo, salve id e consulte GET /v1/tasks/{id} com intervalo mínimo de 5 segundos. Os status públicos são pending, processing, succeeded e failed e o limite é 30 minutos. Não há webhooks, SDK ou batch.
- 01Salve id, status, credits_reserved e identidade da solicitação antes de atualizar a UI.
- 02Use backoff, respeite Retry-After no 429 e não transforme erro de transporte em outra tarefa paga.
- 03Limite a três tarefas de vídeo por conta e 120 solicitações por 60 segundos e API Key.
Cobrança e repetição determinísticas
Na aceitação, credits_reserved é descontado. Salve uma Idempotency-Key por criação; repeti-la com o mesmo corpo retorna a tarefa original.
Falhas elegíveis são reembolsadas uma vez com a validade original. refund_pending indica liquidação e credits_refunded confirma.
Proteger credenciais, propriedade e mídia
Mantenha API Keys no servidor e associe id ao usuário autenticado. Registre identificadores de suporte sem expor prompts, URLs privadas ou credenciais.
Não presuma retenção fixa de vídeo; copie logo o necessário para seu armazenamento com consentimento.
Checklist de produção
- Valide campos do modelo.
- Salve Idempotency-Key e corpo.
- Persista status e consulte a cada 5 segundos ou mais.
- Aplique concorrência e velocidade.
- Trate os quatro status e códigos de liquidação.
- Mantenha credenciais no servidor e defina retenção.
Perguntas frequentes
Com que frequência consultar?
Espere pelo menos 5 segundos e use backoff.
Quando os créditos são cobrados?
Na aceitação, credits_reserved é descontado.
Uma repetição cobra duas vezes?
Não com a mesma Idempotency-Key e corpo.
Como tratar falha final?
Mostre erro seguro, preserve id e verifique credits_refunded.
Quer testar o Seedance?
Compare entradas de texto e imagem na ferramenta online.
Testar Seedance 2.0 online