Generación de Música

La generación de música es asincrónica. POST /v1/music/generations crea una tarea pública de TokenLab y devuelve id / task_id, status y generalmente poll_url. Tu aplicación debe almacenar esa identidad de tarea, mostrar el progreso y consultar hasta un estado terminal.

Elegir El Flujo de Trabajo

Flujo de Trabajo	Campos clave	Notas
Canción completa o instrumental	`model`, `prompt`, `title` opcional, `tags`, `action: "MUSIC"`	Usar cuando el usuario espera audio final
Solo letras	`model`, `prompt`, `action: "LYRICS"`	Usar solo con modelos que expongan la generación de letras
Continuar un clip existente	`continue_clip_id`, `continue_at` opcional	Almacenar la identidad del clip/tarea pública anterior antes de ofrecer la continuación

Consulta el catálogo de modelos actual antes de enviar una lista de modelos codificada:

curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"

Los ejemplos públicos actuales utilizan suno_music para la generación de música. Para flujos solo de letras, envía action: "LYRICS" con un modelo cuyo contrato público documente la generación de letras. Trata los IDs de modelo como IDs públicos de TokenLab, no como una garantía de que los campos específicos del proveedor son campos de contrato público.

Crear Una Tarea de Música

curl https://api.tokenlab.sh/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno_music",
    "prompt": "Una pista de synth-pop animada con voces cálidas y un coro limpio",
    "title": "Estática de la Mañana",
    "tags": "synth-pop, animado",
    "action": "MUSIC"
  }'

Mantén los prompts, títulos y etiquetas visibles para el usuario y seguros para almacenar. No coloques claves de API, URLs privadas o información de enrutamiento interno en ningún campo de prompt.

Consultar Para Completar

Usa poll_url primero. Si tu cliente necesita una ruta fija, llama a GET /v1/tasks/{id} con el id o task_id devuelto.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Los estados públicos esperados son pending, processing, completed y failed. Una tarea de música completada puede incluir audio_url, video_url, title, lyrics y metadatos normalizados. Almacena las URLs finales en tu propia base de datos para que el usuario pueda reabrir el resultado sin reiniciar la generación.

Manejo de UI y Estado

Muestra un estado pendiente inmediatamente después de la creación de la tarea.
Consulta cada 5-10s para tareas largas, luego detente en completed o failed.
No muestres un reproductor final hasta que la tarea esté completed y exista un audio_url.
Para tareas solo de letras, renderiza la salida de texto por separado de las tareas de audio para que los usuarios entiendan lo que están comprando.
Al actualizar, reanuda desde el task_id almacenado en lugar de crear una nueva tarea.

Facturación y Conciliación

Las tareas de música pueden reservar una cantidad estimada en el momento de la creación y liquidar después de que se conozca el estado terminal. Almacena request_id, task_id, modelo, endpoint y billing_transaction_id cuando aparezca. Usa los registros de uso de la API de Gestión para la conciliación en lugar de los IDs de tarea del proveedor.

Errores Comunes

Síntoma	Causa probable	Solución
Tarea creada pero sin reproductor	La tarea aún está pendiente o completada sin `audio_url`	Sigue consultando hasta el estado terminal, luego maneja la salida faltante como un trabajo fallido del usuario
Canciones duplicadas después de la actualización	La UI recreó la tarea en lugar de reanudar	Persiste y reutiliza `task_id`
La tarea de letras no devuelve audio	`action: "LYRICS"` es solo texto	Separa las rutas de UI de letras y música
Parámetro no soportado	El campo no está en el contrato público del modelo	Elimina los campos específicos del proveedor o elige un modelo que los documente

Referencia de API

Tema	Referencia
Crear Música	Crear Música
Obtener Estado de Música	Obtener Estado de Música
Obtener Estado de Tarea	Obtener Estado de Tarea
Listar Modelos	Listar Modelos
Facturación y Precios	Facturación y Precios

​Elegir El Flujo de Trabajo

​Crear Una Tarea de Música

​Consultar Para Completar

​Manejo de UI y Estado

​Facturación y Conciliación

​Errores Comunes

​Referencia de API