Back to home
AuraForge API

API Documentation

Everything you need to integrate AuraForge's music and image generation into your application. Simple REST endpoints, Bearer token auth, and predictable JSON responses.

Rate limit: 15 req/minBearer token auth

Introdução

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).

Autenticação

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"

Rate Limiting

Limites de utilização da API.

A API aplica os seguintes limites:

  • 15 requests/min por API key
  • 10 gerações/min por user

Ao exceder um limite, a API responde com 429 Too Many Requests. O header Retry-After indica quantos segundos esperar.

Music Generation

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 caracteres
  • title — título da faixa
  • style — estilo musical
  • model — "studio-pro" | "balanced" | "fast"
  • instrumental — boolean, sem vozes
  • custom_mode — boolean, modo custom

Resposta

{
  "success": true,
  "generationId": "cm8abc123",
  "status": "PROCESSING"
}

Image Generation

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 caracteres
  • ratio — "1:1" | "16:9" | "9:16"
  • model — "standard" | "premium"

Resposta

{
  "success": true,
  "generationId": "cm8def456",
  "status": "PROCESSING"
}

Image Editing (img2img)

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ção
  • imageUrls — array de 1 a 5 URLs de imagens
  • ratio — "1:1" | "16:9" | "9:16"

Resposta

{
  "success": true,
  "generationId": "cm8ghi789",
  "status": "PROCESSING"
}

Polling for Results

GET /api/v1/generations/{id}

GET /api/v1/generations/{id} — consulta o estado de uma geração.

  • QUEUED — em fila de espera
  • PROCESSING — a processar
  • COMPLETED — concluída
  • FAILED — falhou
curl 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));
  }
}

Error Handling

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 Error

Exemplo de erro

{
  "error": "Rate limit exceeded. Try again in 30 seconds."
}

Code Examples

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"]

Ready to build?

Create an account and get your API key in seconds.

Get started free