API Local REST

SpectraForge expone un servidor HTTP local que permite a otras aplicaciones o IA (como scripts de Python, agentes locales u otras herramientas) solicitar la generación de música o portadas utilizando el mismo flujo y motor (MiniMax) que la interfaz gráfica principal de la aplicación.

Por defecto, la API corre en el puerto 14201, pero este puede cambiarse desde el modal de configuración de la interfaz.

URL base por defecto: http://localhost:14201

Swagger UI: puedes explorar la documentación interactiva e invocar directamente los endpoints visitando http://localhost:14201/api/docs en tu navegador mientras la aplicación está en ejecución.

1. Health Check

Comprueba si la API está funcionando.

Endpoint: GET /
Respuesta: 200 OK
Body: SpectraForge Local API is running

2. Generar Música

Solicita la creación de una canción. Equivalente a usar la pestaña Crear de la interfaz.

Endpoint: POST /api/v1/generate/music
Content-Type: application/json

Body (JSON)

{
  "prompt": "Un hombre caminando solo por el desierto bajo el sol abrasador",
  "instrumental": false,
  "lyrics": "[Verse]\nCaminando en la arena caliente...",
  "lyrics_optimizer": true,
  "moods": ["Melancholic", "Epic"],
  "instruments": ["Acoustic Guitar", "Duduk"],
  "energy": 60,
  "title": "El Caminante del Sol",
  "artist": "ZephirC",
  "album": "Crónicas del Desierto",
  "year": "2026",
  "genre": "Folk Cinematic",
  "cover_prompt": "Ilustración épica de un hombre en el desierto rojo",
  "export_wav": false,
  "negative_prompt": "voces femeninas, electrónica",
  "references_prompt": "",
  "vocals": "voz masculina rasposa",
  "tempo": "lento",
  "bpm": 80,
  "key": "A menor",
  "use_case": "soundtrack",
  "structure": "intro-inst-verse-interlude-verse-pre_chorus-chorus-transition-verse-build_up-chorus-break-solo-interlude-bridge-hook-chorus-chorus-outro",
  "extra": ""
}

Nota: todos los campos son obligatorios en la estructura JSON, aunque pueden enviarse vacíos ("" o listas vacías []), a excepción de los estrictos mencionados arriba.

Respuesta (JSON)

Éxito (200 OK)

{
  "success": true,
  "data": {
    "local_path": "D:\\Musica\\IA\\el_caminante_del_sol_uuid.mp3",
    "lyrics": "[Verse]\nCaminando en la arena caliente...",
    "extra_info": null
  },
  "error": null
}

3. Generar Portada (Cover)

Genera una nueva imagen y la asigna como portada de un MP3 existente.

Endpoint: POST /api/v1/generate/cover
Content-Type: application/json

Body (JSON)

{
  "prompt": "Ilustración de un paisaje desértico con sol brillante",
  "mp3_path": "D:\\Musica\\IA\\mi_cancion.mp3",
  "aspect_ratio": "1:1"
}

aspect_ratio es opcional, puede omitirse (por defecto es 1:1).

Respuesta (JSON)

Éxito (200 OK)

{
  "success": true,
  "cover_path": "D:\\Musica\\IA\\mi_cancion.jpg",
  "error": null
}

4. Generar Imágenes Puras

Genera una o varias imágenes de forma independiente y las guarda en la ruta especificada, sin acoplarlas a ningún archivo de audio. Es útil para crear recursos visuales o probar el generador de imágenes con distintos formatos.

Endpoint: POST /api/v1/generate/image
Content-Type: application/json

Body (JSON)

{
  "prompt": "Un robot de estilo steampunk tocando el violín",
  "aspect_ratio": "16:9",
  "output_dir": "D:\\MisImagenes"
}

aspect_ratio es opcional, puede omitirse (por defecto es 1:1).

[!IMPORTANT] Nota para Agentes de IA / Scripts de Automatización: La generación de cada imagen tarda entre 30 y 50 segundos. Para procesar múltiples peticiones respetando los límites de ráfaga (rate limits) del proveedor, las peticiones DEBEN desfasarse (staggering) de forma asíncrona. Regla estricta: tu script/agente debe disparar la 1.ª petición sin quedarse bloqueado esperando el cuerpo de la respuesta (fire-and-forget o promesas en paralelo), hacer una pausa exacta (sleep/delay) de 5 a 10 segundos, disparar la 2.ª petición, esperar otros 5 a 10 segundos, etc. (hasta 10 en fila). De esta forma, se diluye el impacto en el servidor remoto sin que el código de la IA se quede congelado ni bloqueado esperando a que las imágenes se generen una por una.

Respuesta (JSON)

Éxito (200 OK)

{
  "success": true,
  "image_paths": [
    "D:\\MisImagenes\\img_1719973215809.jpg"
  ],
  "error": null
}