Guías de medios
Generación de música
Crea canciones o letras y espera a que el audio esté terminado
La generación de música es asíncrona. POST /v1/music/generations devuelve un ID de tarea, un estado y, por lo general, una poll_url. Realiza peticiones GET /v1/tasks/{id} con ese ID hasta que la tarea esté completed (completada) o failed (fallida).
Elige qué crear
| Qué crear | Campos clave | Notas |
|---|---|---|
| Canción completa o instrumental | model, mv, prompt, opcional title, tags, action: "MUSIC" | Úsalo cuando el usuario espere el audio final |
| Solo letras | model, prompt, action: "LYRICS" | Úsalo solo con modelos que expongan la generación de letras |
| Continuar un clip existente | model, mv, prompt, continue_clip_id, opcional continue_at | Mantén el ID del clip anterior |
| Hacer una versión o extender tu propio audio | model, mv, prompt, audio_url, opcional audio_operation | audio_url debe ser una URL pública. audio_operation es upload-cover por defecto; upload-extend también requiere continue_at |
| Añadir instrumental, reemplazar una sección o separar pistas | audio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation o advanced-split | Cada operación tiene sus propios campos requeridos; consulta Crear música |
Obtén la lista actual de modelos de música desde:
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
-H "Authorization: Bearer sk-your-api-key"El ejemplo a continuación utiliza suno-music con mv: "chirp-v6". Otros modelos de música, como stable-audio-3, utilizan campos diferentes como duration y output_format; lee primero los detalles del modelo. Para solo letras, elige un modelo que documente la generación de letras, envía action: "LYRICS" y omite mv.
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",
"mv": "chirp-v6",
"prompt": "An upbeat synth-pop track with warm vocals and a clean chorus",
"title": "Morning Static",
"tags": "synth-pop, upbeat",
"action": "MUSIC"
}'Los prompts, títulos y etiquetas pueden aparecer en el historial de tu producto. Nunca incluyas claves de API, URLs privadas o datos de diagnóstico en ellos.
Obtener el audio terminado
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"Estructura de la respuesta
La respuesta de creación es un registro de tarea, no el audio final:
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"created": 1706000000,
"model": "suno-music"
}Una respuesta de sondeo completada puede incluir los campos de medios finales:
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "completed",
"audio_url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"video_url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"image_url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"title": "Morning Static",
"lyrics": "[Verse 1]\n...",
"media_retention": {
"days": 30,
"items": [
{
"url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"kind": "audio",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"kind": "video",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"kind": "image",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
}
]
}
}Los campos de medios finales no están presentes hasta que el status sea completed. Las tareas fallidas devuelven status: "failed" con un error.
Los estados son pending, processing, completed y failed. Una tarea completada puede incluir audio_url, video_url, title, lyrics y otros metadatos. Las URLs de medios son URLs de TokenLab que permanecen válidas durante 30 días; descarga o guarda cualquier resultado que necesites conservar por más tiempo.
Mostrar el estado correcto
- Muestra un estado pendiente inmediatamente después de la creación de la tarea.
- Realiza sondeos cada
5-10spara tareas largas, luego detente cuando el estado seacompletedofailed. - No muestres un reproductor final hasta que la tarea esté
completedy exista unaaudio_url. - Para tareas de solo letras, renderiza la salida de texto por separado de las tareas de audio para que los usuarios entiendan lo que están adquiriendo.
- Al actualizar, reanuda desde el
task_idalmacenado en lugar de crear una nueva tarea.
Registros de facturación
Las tareas de música pueden reservar una cantidad estimada al crearse. La cantidad final se registra después de la finalización o el fallo. Guarda el request_id, task_id, modelo, endpoint y billing_transaction_id cuando aparezcan; utiliza los registros de uso de la Management API para el cargo final.
Errores comunes
| Síntoma | Causa probable | Solución |
|---|---|---|
| Tarea creada pero sin reproductor | La tarea sigue pendiente o se completó sin audio_url | Sigue realizando sondeos hasta que finalice, luego maneja la salida faltante como un trabajo de usuario fallido |
| Canciones duplicadas tras actualizar | La interfaz recreó la tarea en lugar de reanudarla | Persiste y reutiliza el task_id |
| Tarea de letras no devuelve audio | action: "LYRICS" es solo texto | Separa las rutas de interfaz de letras y música |
| Parámetro no soportado | El modelo seleccionado no acepta el campo | Elimínalo o elige un modelo que lo documente |
Referencia de la 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 |