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é crearCampos claveNotas
Canción completa o instrumentalmodel, mv, prompt, opcional title, tags, action: "MUSIC"Úsalo cuando el usuario espere el audio final
Solo letrasmodel, prompt, action: "LYRICS"Úsalo solo con modelos que expongan la generación de letras
Continuar un clip existentemodel, mv, prompt, continue_clip_id, opcional continue_atMantén el ID del clip anterior
Hacer una versión o extender tu propio audiomodel, mv, prompt, audio_url, opcional audio_operationaudio_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 pistasaudio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation o advanced-splitCada 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-10s para tareas largas, luego detente cuando el estado sea completed o failed.
  • No muestres un reproductor final hasta que la tarea esté completed y exista una audio_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_id almacenado 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íntomaCausa probableSolución
Tarea creada pero sin reproductorLa tarea sigue pendiente o se completó sin audio_urlSigue realizando sondeos hasta que finalice, luego maneja la salida faltante como un trabajo de usuario fallido
Canciones duplicadas tras actualizarLa interfaz recreó la tarea en lugar de reanudarlaPersiste y reutiliza el task_id
Tarea de letras no devuelve audioaction: "LYRICS" es solo textoSepara las rutas de interfaz de letras y música
Parámetro no soportadoEl modelo seleccionado no acepta el campoElimínalo o elige un modelo que lo documente

Referencia de la API

TemaReferencia
Crear músicaCrear música
Obtener estado de músicaObtener estado de música
Obtener estado de tareaObtener estado de tarea
Listar modelosListar modelos
Facturación y preciosFacturación y precios

En esta página