Conceitos

Erros & limites

Erros são JSON previsível. Cada job também reporta o quanto custou em credits_charged.

Formato do erro

Toda falha vem com success: false e um objeto error com code estável (para o seu código ramificar) e message legível:

json

{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits."
  }
}

Códigos comuns

HTTP	code	O que aconteceu
401	`invalid_api_key`	Chave ausente, malformada, inválida ou revogada.
403	`api_disabled`	API desligada globalmente, ou sua conta não está no beta / sem plano ativo.
400	`invalid_request`	Parâmetros inválidos (campo faltando, valor fora do enum/range).
400	`insufficient_credits`	Saldo insuficiente para o job. Consulte `GET /balance` e recarregue.
404	`not_found`	Slug de modelo ou id de geração inexistente.
429	`rate_limit`	Limite de taxa estourado. Espere e tente de novo (backoff).

Falhas de job (assíncronas)

Os erros acima são da requisição (chegam no HTTP do POST /generations). Um job aceito pode ainda falhar durante o processamento — nesse caso ele volta com status: "failed" e um error.code estável, um destes:

code	O que aconteceu
`insufficient_credits`	Saldo insuficiente para cobrir o job.
`content_policy_violation`	Prompt ou mídia recusados por política de conteúdo.
`generation_timeout`	O job excedeu o tempo máximo de processamento.
`rate_limited`	Limite de requisições por minuto excedido durante o processamento.
`invalid_input`	Parâmetro obrigatório ausente ou fora do schema do modelo.
`generation_failed`	Falha genérica no processamento do job.
`copyright_conflict`	Áudio recusado por direitos autorais ou conflito na fonte. Não repita automaticamente o mesmo arquivo. Use uma gravação própria ou autorizada.

São os mesmos códigos listados em cada página de modelo. Ramifique pelo code, nunca pela message.

Limites de taxa

As gerações são limitadas a cerca de 20 por minuto por conta (uploads têm o mesmo teto). O restante da superfície /dev tem um limite global mais alto. Ao receber 429, aplique backoff exponencial antes de repetir.

Créditos

credits_charged e credits_net mostram o custo líquido após estornos. credits_debited preserva o débito inicial e credits_refunded informa o estorno efetivamente registrado. Exemplo de falha estornada: credits_debited: 29, credits_refunded: 29, credits_charged: 0, credits_net: 0. API, MCP e webhooks usam os mesmos campos.

Cover de áudio

Use suno-upload-and-cover com audio_url de um arquivo público e autorizado. No modo simples, o prompt descreve a transformação (até 500 caracteres). No modo customizado, envie custom_mode: true, style, title e a letra em lyrics ou prompt quando não instrumental. instrumental e o alias make_instrumental são aceitos. Versões: V4, V4_5, V4_5ALL, V4_5PLUS, V5 e V5_5. A fonte deve ter no máximo 8 minutos; V4_5ALL aceita até 1 minuto. Persona exige modo customizado e V5/V5_5; duração de saída de 10–360 segundos exige modo customizado e V5_5. A aceitação técnica não garante aprovação do conteúdo.

Cada geração debita créditos do saldo da conta. O custo é específico do modelo/tool e volta em credits_charged no job concluído. Acompanhe o saldo a qualquer momento:

bash

curl https://caranguejo.art/api/v1/dev/balance \
  -H "Authorization: Bearer $CK"

json

{ "data": { "credits": 4820 } }