API de música con IA para desarrolladores: canciones con voz por REST, MCP y CLI

La API de música de eroq hace canciones completas con voz e instrumentos, o instrumentales, a partir de una frase o de tu propia letra. Es el mismo motor que el del estudio de música, Music One, con los mismos créditos y la misma clave que el resto de la API de eroq. Esta guía cubre la solicitud, el trabajo asíncrono, los webhooks, la facturación y la herramienta MCP para agentes. La referencia está en /docs/music.

Dos formas de describir una canción

• Simple: envía prompt, la canción en una frase. El compositor escribe el estilo, la letra y un título, incluidos en el precio.
• Custom: envía tu propio style (idioma, voces, género, tempo, instrumentos) y tus lyrics, con las etiquetas de sección cada una en su línea: [Intro], [Verse], [Pre-Chorus], [Chorus], [Bridge], [Outro]. Un style sin lyrics recibe una letra escrita para él.

Añade instrumental: true para quitar las voces (la letra se ignora entonces). Hace falta al menos uno de prompt, style o lyrics.

Empieza una canción

curl https://eroq.ai/v1/music/generations \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eroq-music-one",
    "prompt": "a melancholy synth-pop song about leaving a small town at night, warm female vocal",
    "seconds": 120,
    "n": 2
  }'

Los parámetros que importan:

• seconds: la duración, de 30 a 240 en pasos de 30. Se ajusta a esa cuadrícula y se cobra según la duración solicitada.
• n: tomas, 1 o 2 (2 por defecto). Cada toma es su propio trabajo, con su propia semilla y su propio cobro.
• seed: tomas reproducibles; la toma N se genera con seed + N - 1.
• title: hasta 80 caracteres; si lo omites, el compositor le pone nombre.
• folder_id: la carpeta de la Biblioteca a la que llegan las tomas.

Una canción lleva minutos de GPU, así que la llamada cobra, inicia un trabajo por toma y responde 202:

{
  "id": "4d2a91c0-…",
  "object": "music.generation",
  "status": "processing",
  "model": "eroq-music-one",
  "seconds": 120,
  "title": "Leaving Light",
  "style": "english, female vocals, synth-pop, 104 bpm, warm analog synths",
  "lyrics": "[Verse]\nStreetlights fade behind the bus\n…",
  "instrumental": false,
  "jobs": [
    { "id": "4d2a91c0-…", "poll": "/v1/music/generations/4d2a91c0-…", "take": 1, "seed": 182736 },
    { "id": "9b07e3f1-…", "poll": "/v1/music/generations/9b07e3f1-…", "take": 2, "seed": 182737 }
  ],
  "usage": { "credits_spent": 24, "credits_remaining": 852 }
}

La respuesta repite el title, el style y las lyrics a partir de los que se genera la canción, así que en el modo Simple ves lo que escribió el compositor.

Consulta cada toma

Consultar GET /v1/music/generations/{id} es gratis. Hazlo cada pocos segundos hasta que status sea succeeded o failed:

const BASE = 'https://eroq.ai/v1'
const headers = { Authorization: `Bearer ${process.env.EROQ_API_KEY}` }

async function waitForTake(id, { every = 5000, deadline = 15 * 60_000 } = {}) {
  const started = Date.now()
  while (Date.now() - started < deadline) {
    const take = await fetch(`${BASE}/music/generations/${id}`, { headers }).then(r => r.json())
    if (take.status === 'succeeded') return take.data[0]   // { url, content_type, seconds, library_id }
    if (take.status === 'failed') throw new Error(take.error?.message ?? 'take failed')
    await new Promise(resolve => setTimeout(resolve, every))
  }
  throw new Error('still rendering — poll again later')
}

Una toma terminada trae una URL de MP3 (audio/mpeg), su duración real en seconds (una canción puede encontrar su final un poco antes de la duración solicitada) y su library_id: cada toma se guarda además en tu Biblioteca con su receta. Los id de trabajo caducan 24 horas después de crearse, así que descarga o guarda el MP3 antes si lo sirves tú.

O recibe un webhook firmado

Registra un endpoint en el panel de desarrolladores y suscríbelo a music.generation.succeeded y music.generation.failed. Cada entrega es un POST con JSON firmado en la cabecera eroq-signature (t=<timestamp>,v1=<HMAC-SHA256 of "t.body">), el mismo esquema que los eventos de video, explicado en trabajos asíncronos y webhooks firmados. El payload lleva el id del trabajo y una result_url, nunca el audio en sí.

Responde 2xx rápido y haz el trabajo después; mantén el polling como plan B para todo lo que no te haya llegado.

Facturación

• 3 créditos por cada 30 segundos de canción empezados, por toma, según la duración solicitada: 6 créditos por un minuto, 18 por tres, 24 por cuatro.
• n: 2 lo duplica. Usa n: 1 cuando no necesites elegir.
• Una toma que falla, o que no termina dentro del plazo del motor, se reembolsa por separado; la otra toma se entrega igualmente.
• Los mismos créditos pagan imágenes, video, voz y chat. Un paquete de $10 son 1,000 créditos; no hace falta ningún plan.

Política de contenido

La política se aplica a todo lo que envías y a lo que escribe el compositor. Dentro de ella, la letra va sin censura: las palabrotas y los temas oscuros están permitidos. Se rechaza: cualquier cosa que involucre a menores, personas reales identificables sin su consentimiento, contenido ilegal y violencia sexual; el compositor nunca nombra a un artista real. Una solicitud rechazada responde 400 content_blocked y no cobra nada, o se reembolsa cuando el problema está en la letra que escribió el compositor.

Si el motor no está activo en un despliegue, la llamada responde 503 model_unavailable antes de cobrar nada; GET /v1/engines lo indica.

Para agentes de IA: MCP

El servidor MCP de eroq expone generate_music a ChatGPT, Claude, Claude Code, Cursor y Codex. La herramienta acepta prompt (una frase) o style + lyrics, además de title, instrumental y seconds, espera un momento y devuelve la canción o un id de trabajo que se consulta con get_music_status. Conéctalo desde la página MCP. Pídele a tu asistente «hazme una intro lo-fi de 30 segundos para mi podcast» y llamará a la herramienta.

Desde la terminal: la CLI

eroq music "a melancholy synth-pop song about leaving a small town" -s 120
eroq music --style "English, warm male vocal, folk" --lyrics "[Verse]…" -n 1 -o song.mp3
eroq music "a calm lo-fi beat for studying" --instrumental -s 60

La CLI consulta hasta que el MP3 está listo y lo guarda como archivo. Su comando eroq mcp ejecuta un servidor MCP local que guarda las canciones como archivos en tu directorio de trabajo, algo que les viene bien a los agentes de programación.

Preguntas frecuentes

¿Hay una API de música con IA que genere canciones con voz?

Sí. POST /v1/music/generations hace canciones con voz, o instrumentales, a partir de una frase o de tu propio estilo y tu propia letra. Es asíncrona: un trabajo por toma, que se consulta gratis o se entrega por webhook.

¿Cuánto cuesta la API de música?

3 créditos por cada 30 segundos empezados y por toma, lo mismo que en el estudio. Una canción de dos minutos son 12 créditos por toma.

¿Cuánto puede durar una canción generada?

De 30 a 240 segundos, en pasos de 30.

¿Qué eventos de webhook envía una canción?

music.generation.succeeded y music.generation.failed, firmados con la cabecera eroq-signature.

¿Puedo escribir mi propia letra a través de la API?

Sí. Envía style y lyrics con etiquetas de sección como [Verse] y [Chorus], cada una en su línea, hasta 3,000 caracteres de letra.

¿Puede un asistente de IA hacer canciones con eroq?

Sí, con la herramienta MCP generate_music, disponible en ChatGPT, Claude, Claude Code, Cursor y Codex en cuanto conectas eroq.