curl --request POST \
--url https://api.apimart.ai/v1/music/generations/download \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"]
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/music/generations/download",
headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
json={
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"],
},
)
print(response.json())
const response = await fetch(
"https://api.apimart.ai/v1/music/generations/download",
{
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "suno",
task_id: "task_01JGXXXXXXXXXXXX",
audio_index: 1,
formats: ["mp3", "wav"],
}),
},
);
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01JHXXXXXXXXXXXX"
}
]
}
{
"error": {
"message": "`formats` contains unsupported format `flac`. Supported: mp3 / m4a / wav",
"type": "invalid_request_error",
"code": "invalid_source_reference"
}
}
{
"error": {
"code": 401,
"message": "Falha na autenticação. Verifique sua chave de API.",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "Saldo insuficiente",
"type": "payment_required"
}
}
Suno
Baixar arquivos de áudio
- Baixe músicas do Suno como MP3, M4A ou WAV
- Solicite vários formatos de uma vez e receba uma URL para cada arquivo
- Selecione a música de origem com task_id e audio_index
- Envio assíncrono e consulta do resultado pelo endpoint de tarefas de música
POST
/
v1
/
music
/
generations
/
download
curl --request POST \
--url https://api.apimart.ai/v1/music/generations/download \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"]
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/music/generations/download",
headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
json={
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"],
},
)
print(response.json())
const response = await fetch(
"https://api.apimart.ai/v1/music/generations/download",
{
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "suno",
task_id: "task_01JGXXXXXXXXXXXX",
audio_index: 1,
formats: ["mp3", "wav"],
}),
},
);
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01JHXXXXXXXXXXXX"
}
]
}
{
"error": {
"message": "`formats` contains unsupported format `flac`. Supported: mp3 / m4a / wav",
"type": "invalid_request_error",
"code": "invalid_source_reference"
}
}
{
"error": {
"code": 401,
"message": "Falha na autenticação. Verifique sua chave de API.",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "Saldo insuficiente",
"type": "payment_required"
}
}
O antigo endpoint
POST /v1/music/generations/wav foi descontinuado. Ele permanece temporariamente compatível e equivale ao novo endpoint com formats: ["wav"]. Novas integrações devem usar POST /v1/music/generations/download.Selecione a música de origem: envie o
task_id da tarefa que criou o áudio e use audio_index para escolher uma faixa do resultado music[]. O índice começa em 1 e o padrão é 1.curl --request POST \
--url https://api.apimart.ai/v1/music/generations/download \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"]
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/music/generations/download",
headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
json={
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"],
},
)
print(response.json())
const response = await fetch(
"https://api.apimart.ai/v1/music/generations/download",
{
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "suno",
task_id: "task_01JGXXXXXXXXXXXX",
audio_index: 1,
formats: ["mp3", "wav"],
}),
},
);
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01JHXXXXXXXXXXXX"
}
]
}
{
"error": {
"message": "`formats` contains unsupported format `flac`. Supported: mp3 / m4a / wav",
"type": "invalid_request_error",
"code": "invalid_source_reference"
}
}
{
"error": {
"code": 401,
"message": "Falha na autenticação. Verifique sua chave de API.",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "Saldo insuficiente",
"type": "payment_required"
}
}
Autenticação
string
obrigatório
Todas as APIs exigem Bearer Token. Obtenha sua chave na página de chaves de API.
Authorization: Bearer YOUR_API_KEY
Parâmetros da solicitação
string
padrão:"suno"
Nome do modelo. Use
suno; o padrão também é suno.string
obrigatório
ID da tarefa que criou a música de origem.A tarefa deve pertencer à conta atual, estar concluída e conter áudio para download. Geração, extensão, cover e stems são aceitos; tarefas apenas de texto, como letras ou análise de BPM, não são.
integer
padrão:"1"
Número da faixa no resultado
music[].- Começa em
1 - Padrão:
1 - Não pode exceder o número de faixas da tarefa
string[]
Array de formatos solicitados com pelo menos um item.Valores:
mp3, m4a, wav.Vários formatos podem ser solicitados juntos. Maiúsculas e minúsculas são ignoradas, duplicados são removidos e a ordem do resultado segue a solicitação.string
Para um único formato, pode substituir
formats.Exemplo: "format": "mp3"Use
formats ou format. Se ambos faltarem ou o array estiver vazio, a API retorna HTTP 400.Resposta do envio
O envio bem-sucedido retorna um novotask_id da tarefa de download.
data é um array; leia data[0].task_id. Esse ID pertence à nova tarefa de download e difere do task_id da música enviado na solicitação.Consultar o resultado
Use o ID da tarefa de download:GET /v1/music/tasks/{task_id}
completed nem failed, consulte a cada 2 segundos por no máximo 60 segundos.
Concluído
{
"code": 200,
"data": {
"id": "task_01JHXXXXXXXXXXXX",
"status": "completed",
"progress": 100,
"cost": 0.01,
"credits_cost": 0.1,
"result": {
"music_id": "518c74ee-62ac-4ccd-b3d9-7003acd12ad7",
"files": [
{
"format": "mp3",
"url": "https://assets.apimart.ai/audio/example.mp3"
},
{
"format": "wav",
"url": "https://assets.apimart.ai/audio/example.wav"
}
],
"wavUrl": "https://assets.apimart.ai/audio/example.wav"
}
}
}
result.files[]:
| Campo | Tipo | Descrição |
|---|---|---|
format | string | mp3 / m4a / wav |
url | string | URL de download |
result.wavUrl existe apenas para compatibilidade com a antiga API WAV. O novo código deve sempre usar result.files[].Em processamento
{
"code": 200,
"data": {
"id": "task_01JHXXXXXXXXXXXX",
"status": "processing",
"progress": 50,
"created": 1756800000
}
}
result. Continue consultando.
Falha
Tarefas com falha recebem reembolso automático e retornamcost: 0. Exiba error.message e permita tentar novamente.
URLs dos arquivos
Os resultados normalmente usam o domínio de arquivos da APIMart. Se a transferência falhar, pode ser retornada uma URL CDN do provedor sem garantia de validade.Baixe e armazene o arquivo rapidamente. Não use uma URL temporária como armazenamento permanente.
Erros
Erros de validação retornam HTTP 400 antes da criação e cobrança.| Texto do erro | Motivo |
|---|---|
formats is required / must contain at least one | Formato ausente |
unsupported format | Valor diferente de mp3 / m4a / wav |
task_id is required / invalid task_id format | ID ausente ou inválido |
source task not found | Tarefa inexistente ou de outra conta |
audio_index N out of range | Número da faixa fora do intervalo |
track #N has no music_id | Tarefa não concluída ou faixa sem áudio |
model_price_not_configured significa que o preço suno@download não está configurado; contate o suporte.
Cobrança e downloads repetidos
- Uma solicitação com vários formatos gera uma cobrança
- Reenviar a mesma música gera nova cobrança, mesmo no mesmo formato
- Solicitar outro formato em uma nova tarefa também gera cobrança
- Tarefas com falha são reembolsadas automaticamente
Reutilize URLs já recebidas e desative o botão durante a solicitação para evitar envios e cobranças duplicadas.
Migração da API antiga
| Item | Antigo | Novo |
|---|---|---|
| Caminho | /v1/music/generations/wav | /v1/music/generations/download |
| Formatos | Apenas WAV | MP3 / M4A / WAV, múltiplos |
| Parâmetro | — | formats ou format |
| Resultado | result.wavUrl | result.files[] |
/generations/download.
Response
integer
Código de resposta; 200 em caso de sucesso