Everything you need to integrate AuraForge's music and image generation into your application. Simple REST endpoints, Bearer token auth, and predictable JSON responses.
Visão geral da API AuraForge.
A AuraForge API permite gerar música e imagens com IA a partir de prompts de texto. Todos os endpoints são REST, respondem em JSON e usam autenticação Bearer token.
Base URL: https://api.auraforge.ai
Os endpoints disponíveis cobrem geração de música (Suno v4), geração de imagens (DALL-E 3) e edição de imagens (img2img).
Como obter e usar API keys (Bearer token).
Todas as chamadas à API exigem uma API key enviada no header Authorization como Bearer token. Crie a sua key em Dashboard → API Keys. As keys têm o prefixo af_.
curl https://api.auraforge.ai/api/v1/generations \ -H "Authorization: Bearer af_sua_api_key"
Limites de utilização da API.
A API aplica os seguintes limites:
Ao exceder um limite, a API responde com 429 Too Many Requests. O header Retry-After indica quantos segundos esperar.
POST /api/v1/music/generate
POST /api/v1/music/generate — gera uma faixa musical a partir de um prompt.
curl -X POST https://api.auraforge.ai/api/v1/music/generate \
-H "Authorization: Bearer af_sua_api_key" \
-H "Content-Type: application/json" \
-d '{
"prompt": "upbeat synthwave track about neon cities",
"title": "Neon Drive",
"style": "synthwave",
"model": "studio-pro",
"instrumental": true,
"custom_mode": false
}'Parâmetros
prompt (required) — max 5000 caracterestitle — título da faixastyle — estilo musicalmodel — "studio-pro" | "balanced" | "fast"instrumental — boolean, sem vozescustom_mode — boolean, modo customResposta
{
"success": true,
"generationId": "cm8abc123",
"status": "PROCESSING"
}POST /api/v1/images/generate
POST /api/v1/images/generate — gera uma imagem a partir de um prompt.
curl -X POST https://api.auraforge.ai/api/v1/images/generate \
-H "Authorization: Bearer af_sua_api_key" \
-H "Content-Type: application/json" \
-d '{
"prompt": "cyberpunk city at night, neon lights",
"ratio": "16:9",
"model": "standard"
}'Parâmetros
prompt (required) — max 4000 caracteresratio — "1:1" | "16:9" | "9:16"model — "standard" | "premium"Resposta
{
"success": true,
"generationId": "cm8def456",
"status": "PROCESSING"
}POST /api/generate/img2img
POST /api/generate/img2img — edita imagens existentes com um prompt.
curl -X POST https://api.auraforge.ai/api/generate/img2img \
-H "Authorization: Bearer af_sua_api_key" \
-H "Content-Type: application/json" \
-d '{
"prompt": "make the sky more dramatic",
"imageUrls": [
"https://example.com/photo1.jpg",
"https://example.com/photo2.jpg"
],
"ratio": "16:9"
}'Parâmetros
prompt (required) — descrição da ediçãoimageUrls — array de 1 a 5 URLs de imagensratio — "1:1" | "16:9" | "9:16"Resposta
{
"success": true,
"generationId": "cm8ghi789",
"status": "PROCESSING"
}GET /api/v1/generations/{id}
GET /api/v1/generations/{id} — consulta o estado de uma geração.
QUEUED — em fila de esperaPROCESSING — a processarCOMPLETED — concluídaFAILED — falhoucurl https://api.auraforge.ai/api/v1/generations/cm8abc123 \ -H "Authorization: Bearer af_sua_api_key"
Resposta
{
"id": "cm8abc123",
"type": "MUSIC",
"status": "COMPLETED",
"prompt": "upbeat synthwave track...",
"model": "studio-pro",
"fileUrl": "https://.../track.mp3",
"duration": 182.5,
"createdAt": "2026-11-10T14:30:00Z"
}Exemplo de polling
async function pollGeneration(id) {
while (true) {
const res = await fetch(`https://api.auraforge.ai/api/v1/generations/${id}`, {
headers: { Authorization: `Bearer ${process.env.AURAFORGE_API_KEY}` },
});
const data = await res.json();
if (data.status === "COMPLETED") return data;
if (data.status === "FAILED") throw new Error("Generation failed");
await new Promise((r) => setTimeout(r, 5000));
}
}Códigos HTTP e mensagens de erro.
A API responde com os seguintes códigos de erro:
400 — Bad Request (prompt inválido)401 — Unauthorized (API key inválida ou ausente)403 — Forbidden (sem permissão)404 — Not Found (recurso inexistente)429 — Too Many Requests (rate limit excedido)500 — Internal Server ErrorExemplo de erro
{
"error": "Rate limit exceeded. Try again in 30 seconds."
}Exemplos em JavaScript/Node.js e Python.
JavaScript / Node.js
const res = await fetch("https://api.auraforge.ai/api/v1/music/generate", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AURAFORGE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
prompt: "upbeat synthwave track about neon cities",
model: "studio-pro",
instrumental: true,
}),
});
const { generationId } = await res.json();Python
import requests
response = requests.post(
"https://api.auraforge.ai/api/v1/music/generate",
headers={
"Authorization": f"Bearer {AURAFORGE_API_KEY}",
"Content-Type": "application/json",
},
json={
"prompt": "upbeat synthwave track about neon cities",
"model": "studio-pro",
"instrumental": True,
},
)
generation_id = response.json()["generationId"]