Guías de medios
Generación de Música
Crea tareas de música o letras, consulta el audio final y almacena de manera segura las salidas musicales para el usuario.
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, mv, 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 e incluyen mv con una versión oficial del modelo Suno, como chirp-v4. Para flujos solo de letras, envía action: "LYRICS" con un modelo cuyos detalles documenten la generación de letras y omite mv. Trata los IDs de modelo como IDs públicos de TokenLab, no como una garantía de que los campos específicos del proveedor sean campos de detalles del modelo.
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-v4",
"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 ni información privada de diagnóstico 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"Forma de la respuesta
La respuesta de creación es un registro de tarea que se consulta por polling, 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 polling completada puede incluir los campos multimedia finales:
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "completed",
"audio_url": "https://cdn.example.com/music/abc123.mp3",
"video_url": "https://cdn.example.com/music/abc123.mp4",
"stream_audio_url": "https://cdn.example.com/music/abc123-stream.mp3",
"image_url": "https://cdn.example.com/music/cover.jpg",
"title": "Morning Static",
"lyrics": "[Verse 1]\n..."
}Los campos multimedia finales no aparecen hasta que status es completed. Las tareas fallidas devuelven status: "failed" con error.
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-10spara tareas largas, luego detente encompletedofailed. - No muestres un reproductor final hasta que la tarea esté
completedy exista unaudio_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_idalmacenado 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 los detalles 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 |