Guia de modelos de API do suno
Resumo
- suno suporta Text-to-Video, Image-to-Video, R2V e Video Edit em um único fluxo.
- Use esta página de guia do modelo para validar parâmetros com exemplos mínimos de requisição e resposta.
- Estabilize primeiro os prompts aqui e depois passe para a integração com a API de produção.
Capacidades principais
- Testes unificados de vários modos:Alterne entre Text-to-Video, Image-to-Video, R2V e Video Edit em um mesmo lugar.
- Validação centrada em parâmetros:Itere rapidamente sobre prompts, durações e referências antes do rollout em produção.
- Passagem pronta para produção:Uma estrutura mínima de requisição e resposta ajuda a mover configurações estáveis para fluxos de API.
Quando usar
- Quando precisar de iteração rápida entre vários modos de geração.
- Quando precisar validar parâmetros e tratamento de erros antes da integração.
Quando não usar
- Para produção assíncrona em lote em larga escala, use diretamente o pipeline da API do servidor.
- Para requisitos rígidos de autenticação e auditoria, priorize a orquestração no backend.
Comportamento em execução
- Esta página de guia do modelo é otimizada para interação e ensaio de parâmetros.
- O painel de saída demonstra a estrutura de resultado da tarefa como orientação de integração.
Requisição mínima
{
"model": "suno",
"mode": "text-to-video",
"input": {
"prompt": "A cinematic city sunrise with soft fog and moving traffic.",
"duration": 5
}
}
Resposta mínima
{
"task_id": "task_xxxxxxxx",
"model": "suno",
"mode": "text-to-video",
"status": "queued",
"created_at": "2026-04-15T00:00:00.000Z"
}
Parâmetros principais
| Parâmetro | Tipo | Obrigatório | Padrão | Intervalo | Descrição |
|---|---|---|---|---|---|
| model | string | Sim | suno | - | Identificador do modelo. Use o valor fixo suno. |
| prompt | string | Sim | - | - | Instrução principal que descreve o sujeito, a ação, a cena e o estilo. |
| aspect_ratio | string | Não | 16:9 | 16:9 | 9:16 |
| duration | integer | Não | 6 | 5 | 10 |
| resolution | string | Não | 720P | 720P | Resolução da saída. Padrão 720P; aceita 720P. |
Erros comuns
| HTTP | Code | Condição de acionamento | Ação corretiva | Política de nova tentativa |
|---|---|---|---|---|
| 400 | invalid_request_error | O payload da requisição não inclui campos obrigatórios ou tem tipos de campo inválidos. | Valide model, mode e o esquema de input antes de enviar. | Tente novamente apenas após corrigir o payload; evite novas tentativas cegas. |
| 401 | authentication_error | O cabeçalho Authorization está ausente ou a chave de API é inválida. | Verifique o formato do token Bearer e o escopo da chave de API. | Tente novamente após corrigir a autenticação; rotacione a chave se as falhas se repetirem. |
| 429 | rate_limit_exceeded | A frequência de requisições, a concorrência ou a cota atual acionam o limite do provedor. | Aplique primeiro um recuo exponencial e depois revise o ritmo de requisições, a concorrência e o uso da cota. | Use backoff exponencial (por exemplo, 1s/2s/4s) com jitter; se persistir, reduza a pressão de envio. |
| 500 | internal_error | Erro transitório do provedor ou falha interna de processamento. | Registre o request id e acione o fluxo de novas tentativas. | Tente novamente 2 a 3 vezes com intervalos curtos; escale se o problema persistir. |
FAQ
- Quando devo usar o suno?
Use-o para validar conceitos de vídeo rapidamente, comparar o comportamento dos modos e convergir prompts antes do rollout da API. - Como escolho entre Text-to-Video e Image-to-Video?
Use Text-to-Video quando tiver apenas instruções; use Image-to-Video quando já tiver quadros-chave ou composição. - Qual é a diferença entre R2V e Video Edit?
R2V foca em geração guiada por referências, enquanto Video Edit foca em modificar recursos de vídeo existentes. - Erro no modelo de imagem ou vídeo: invalid apitype: -1
Isso geralmente indica que a requisição foi enviada para o endpoint errado. Modelos de imagem e vídeo normalmente não usam o endpoint de chat. Em vez disso, envie a requisição HTTP de tarefa conforme a documentação e consulte o endpoint de status da tarefa para obter o resultado. Verifique primeiro o código real da requisição, a URL e o payload. - Uma tarefa de imagem ou vídeo falhou, mas o usuário ainda foi cobrado
Peça primeiro ao usuário o log da tarefa ou uma captura de tela e verifique se aparece consumo de tokens de entrada ou saída. Se houver registro de tokens, provavelmente a requisição foi enviada por um endpoint de chat em vez do fluxo de mídia correto. Modelos de imagem e vídeo normalmente funcionam como APIs HTTP de tarefas assíncronas: envie a tarefa primeiro e depois consulte pelo task id conforme a documentação.







