SunoComprobando

suno-lyrics

texto a letraSalida: TextoEntrada: texto

Cargando precio…

Precio de lista oficial · Sin verificar

Probar en el Playground Obtener clave de API

Parámetros

Obligatorio

Topic Promptprompt: string

Describe lyrics topic in one sentence (≤500 chars) 1–500 chars

Vista previa de la solicitud

{
  "model": "suno-lyrics",
  "input": {}
}

El playground web envía este cuerpo con tu sesión iniciada. Desde código, envía el mismo cuerpo con una clave de API.

Cargo estimado

Cargando precio…

Los créditos se reservan al aceptar una tarea y solo se cobran si tiene éxito. Las tareas fallidas liberan la reserva; los resultados sin confirmar siguen reservados hasta verificarse.

Qué hace

Theme prompt describing desired lyric topic. Output: Pure text lyrics with song structure (Verse/Chorus labels), song title, and style tags. Suitable for quick lyric drafting, creative inspiration, etc. Can be used with Custom Mode for rapid re-creation and audio generation.

Text-Only OutputAuto Section Structure (Verse/Chorus/Bridge)Editable & Reusable

Parámetros de entrada

Solo los campos que acepta este modelo. Los campos obligatorios deben indicarse.

Campo	Tipo	Obligatorio	Predeterminado	Valores permitidos y restricciones
`prompt` Topic Prompt	`string`	obligatorio	—	Describe lyrics topic in one sentence (≤500 chars) 1–500 chars

Límites y comportamiento

Solo asíncrono: envía una tarea y luego consulta el resultado.
prompt: 1–500 chars

Endpoint

Todos los modelos comparten una API de tareas asíncrona. Este modelo se selecciona por su slug.

Enviar

POST https://api.hermes-ai.net/api/v1/jobs

{
  "model": "suno-lyrics",
  "input": {
    "prompt": "A lighthouse on a rocky coast at sunrise, soft light"
  }
}

Después consulta GET /api/v1/jobs/{id} hasta que el estado sea final.

Autenticación

Envía una clave de API con el permiso jobs:create para enviar y jobs:read para consultar.

Encabezado	Valor	Notas
`Authorization`	`Bearer <API key>`	O envía la clave en x-api-key.
`Content-Type`	`application/json`
`Idempotency-Key`	`<unique string ≤128>`	Obligatorio. Reutilízalo solo para reintentar la misma solicitud.

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Notas
`model`	`string`	obligatorio	Slug del modelo en el catálogo.
`input`	`object`	obligatorio	Campos del esquema de entrada del modelo.
`expectedPriceMicros`	`integer`	opcional	Precio que mostraste al usuario. Si no coincide, se devuelve 409 PRICE_CHANGED antes de cualquier cargo.

campos de input

Los campos desconocidos se rechazan con INVALID_MODEL_INPUT.

Campo	Tipo	Obligatorio	Predeterminado	Valores permitidos y restricciones
`prompt` Topic Prompt	`string`	obligatorio	—	Describe lyrics topic in one sentence (≤500 chars) 1–500 chars

Respuesta

202 para una tarea nueva, 200 cuando coincide una repetición con Idempotency-Key. GET /api/v1/jobs/{id} devuelve la misma estructura sin replayed.

Campo	Tipo	Notas
`id`	`string`	ID de tarea de Hermes AI. Úsalo para consultar.
`model`	`string`	Slug del modelo.
`status`	`string`	Consulta los estados de la tarea.
`errorCode`	`string \| null`	Se establece cuando una tarea falla o requiere revisión.
`priceMicros`	`integer`	Cotización fijada al aceptarla, en micro-unidades de USD.
`currency`	`"USD"`
`createdAt / updatedAt`	`string`	Marcas de tiempo ISO 8601.
`assets[]`	`array`	{ id, type, url?, text? }. url es un enlace /api/v1/results/<uuid> del mismo origen.
`replayed`	`boolean`	Solo al enviar. true cuando coincide un reintento idempotente.

Estados de la tarea

Estado	Final	Significado
`queued`	no	Aceptada y a la espera de un trabajador.
`submitting`	no	Enviándose al proveedor del modelo.
`running`	no	El modelo está generando.
`succeeded`	sí	Terminada. Los resultados están en assets.
`failed`	sí	Terminada sin resultado. La reserva se libera.
`reconciliation_required`	sí	The result is being verified. Keep the task ID and do not resubmit automatically.

Errores

Todos los cuerpos de error son { code, error }. Gestiónalos por code.

HTTP	Código	Significado y acción
`401`	`AUTH_REQUIRED`	Falta la clave de API o la sesión, o no es válida.
`403`	`INSUFFICIENT_SCOPE`	La clave de API no tiene el permiso que necesita este endpoint.
`403`	`PERMISSION_DENIED`	Esta credencial no puede realizar la operación.
`429`	`API_KEY_RATE_LIMITED`	Se alcanzó el límite de frecuencia de la clave de API. Respeta Retry-After.
`429`	`API_KEY_USAGE_EXCEEDED`	La clave de API alcanzó su límite de uso. Crea una clave nueva.
`400`	`INVALID_REQUEST`	El cuerpo no es un objeto JSON o falta un valor obligatorio.
`400`	`INVALID_IDEMPOTENCY_KEY`	Idempotency-Key debe tener entre 1 y 128 caracteres ASCII imprimibles.
`400`	`INVALID_MODEL_INPUT`	input no coincide con el esquema del modelo (campo desconocido, campo obligatorio ausente o valor no válido).
`400 / 413`	`INPUT_TOO_LARGE`	El cuerpo de la solicitud supera los 256 KB. Sube primero los archivos multimedia y envía una referencia.
`404`	`REQUEST_NOT_FOUND`	No chat request with this ID belongs to your account.
`404`	`MODEL_NOT_FOUND`	Ningún modelo tiene este slug.
`404`	`JOB_NOT_FOUND`	Ninguna tarea con este ID pertenece a tu cuenta.
`409`	`IDEMPOTENCY_CONFLICT`	Esta Idempotency-Key se usó con otra entrada. Usa una clave nueva para una solicitud nueva.
`409`	`PRICE_CHANGED`	El precio difiere de expectedPriceMicros. Obtén el precio y vuelve a confirmarlo.
`409`	`MODEL_PRICE_UNAVAILABLE`	Este modelo aún no tiene precio configurado, por lo que no puede ejecutarse.
`409`	`PAYMENT_REVIEW_REQUIRED`	A refund left an uncovered balance. Contact support or cover the balance before submitting tasks.
`409`	`INSUFFICIENT_CREDITS`	Los créditos disponibles no cubren el precio de la tarea.
`429`	`RATE_LIMITED`	Demasiados envíos de tareas por minuto. Vuelve a intentarlo más tarde.
`429`	`CONCURRENCY_LIMITED`	Demasiadas tareas sin terminar. Espera a que termine alguna.
`503`	`EXECUTION_UNAVAILABLE`	La ejecución no está configurada para este modelo en este momento.
`429`	`UPSTREAM_RATE_LIMITED`	The model provider is rate limiting chat requests. Retry with backoff; nothing was charged.
`502`	`UPSTREAM_ERROR`	The model provider failed the chat request. Nothing was charged; retry later.
`503`	`PLATFORM_BUDGET_EXCEEDED`	This model is temporarily unavailable. Try again later.
`503`	`EXECUTION_TEMPORARILY_UNAVAILABLE`	La ejecución no está disponible temporalmente. Reintenta con la misma Idempotency-Key.
`503`	`AUTH_UNAVAILABLE`	La autenticación no está disponible temporalmente. Vuelve a intentarlo más tarde.
`503`	`API_UNAVAILABLE`	La API no está disponible temporalmente. Vuelve a intentarlo más tarde.

Guía completa de la API · OpenAPI 3.1

Precio de Hermes AI

Cargando precio…

No se pudo cargar la lista de precios en tiempo real. Actualiza para intentarlo de nuevo.

Precio de lista oficial

Tarifas estándar de API del fabricante en USD, antes de descuentos de canal. Las unidades y especificaciones siguen la fuente oficial.

Precio oficial no verificado para este modelo.

Qué influye en el coste

Resolution, duration and output quantity can affect the quote. Review the rate card and the Playground quote before submitting.

· Only successful tasks are charged. Failed tasks release reserved credits; tasks with an unconfirmed outcome keep their reservation until the result is verified.
· Los reintentos idempotentes con la misma clave no generan un segundo cargo.
· Envía expectedPriceMicros para rechazar la tarea con PRICE_CHANGED si el precio cambió después de mostrarlo.

Estimación

Select the specifications in Playground to see the task quote.

// Facturación

Cómo funciona la facturación

Tasks use prepaid credits. Add credits on the Billing page; your balance updates after payment confirmation.

Cuándo	Efecto
Task accepted	The quoted amount is reserved from your balance.
Task succeeded	The reserved amount is charged once.
Task failed	The reserved amount is returned to your available balance.

Tasks with an unconfirmed outcome keep their reserved credits until the result is verified. Keep the task ID and contact support if you need help.

Payment refunds are reflected in your balance and transaction history on the Billing page.

Solicitud mínima

Solo campos obligatorios, generada a partir del esquema de este modelo. Define HERMES_API_KEY en tu entorno.

# 1. Submit the task (asynchronous; returns 202 with a task id)
curl -X POST https://api.hermes-ai.net/api/v1/jobs \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "model": "suno-lyrics",
  "input": {
    "prompt": "A lighthouse on a rocky coast at sunrise, soft light"
  }
}'

# 2. Poll until status is succeeded, failed or reconciliation_required
curl https://api.hermes-ai.net/api/v1/jobs/TASK_ID \
  -H "Authorization: Bearer $HERMES_API_KEY"