Guía de modelos API de suno
Resumen
- suno admite Text-to-Video, Image-to-Video, R2V y Video Edit en un solo flujo.
- Use esta página de guía del modelo para validar parámetros con ejemplos mínimos de solicitud y respuesta.
- Estabilice primero los prompts aquí y después pase a la integración con la API de producción.
Capacidades principales
- Pruebas unificadas de varios modos:Alterne entre Text-to-Video, Image-to-Video, R2V y Video Edit en un mismo lugar.
- Validación centrada en parámetros:Itere rápidamente sobre prompts, duraciones y referencias antes del despliegue en producción.
- Traspaso listo para producción:Una estructura mínima de solicitud y respuesta ayuda a trasladar configuraciones estables a flujos de API.
Cuándo usarlo
- Cuando necesite iteración rápida entre varios modos de generación.
- Cuando necesite validar parámetros y gestión de errores antes de la integración.
Cuándo no usarlo
- Para producción asíncrona por lotes a gran escala, use directamente el pipeline de la API del servidor.
- Para requisitos estrictos de autenticación y auditoría, priorice la orquestación en el backend.
Comportamiento en ejecución
- Esta página de guía del modelo está optimizada para la interacción y el ensayo de parámetros.
- El panel de resultados muestra la estructura de resultado de la tarea como guía de integración.
Solicitud mínima
{
"model": "suno",
"mode": "text-to-video",
"input": {
"prompt": "A cinematic city sunrise with soft fog and moving traffic.",
"duration": 5
}
}
Respuesta mínima
{
"task_id": "task_xxxxxxxx",
"model": "suno",
"mode": "text-to-video",
"status": "queued",
"created_at": "2026-04-15T00:00:00.000Z"
}
Parámetros clave
| Parámetro | Tipo | Obligatorio | Predeterminado | Rango | Descripción |
|---|---|---|---|---|---|
| model | string | Sí | suno | - | Identificador del modelo. Use el valor fijo suno. |
| prompt | string | Sí | - | - | Instrucción principal que describe el sujeto, la acción, la escena y el estilo. |
| aspect_ratio | string | No | 16:9 | 16:9 | 9:16 |
| duration | integer | No | 6 | 5 | 10 |
| resolution | string | No | 720P | 720P | Resolución de salida. Valor predeterminado 720P; admite 720P. |
Errores frecuentes
| HTTP | Code | Condición de activación | Acción correctiva | Política de reintentos |
|---|---|---|---|---|
| 400 | invalid_request_error | El payload de la solicitud no incluye campos obligatorios o tiene tipos de campo no válidos. | Valide model, mode y el esquema de input antes de enviar. | Reintente solo después de corregir el payload; evite reintentos ciegos. |
| 401 | authentication_error | Falta la cabecera Authorization o la clave de API no es válida. | Verifique el formato del token Bearer y el ámbito de la clave de API. | Reintente después de corregir la autenticación; rote la clave si los fallos se repiten. |
| 429 | rate_limit_exceeded | La frecuencia de solicitudes, la concurrencia o la cuota actual activan el límite del proveedor. | Aplique primero un retroceso exponencial y luego revise el ritmo de solicitudes, la concurrencia y el uso de la cuota. | Use retroceso exponencial (por ejemplo, 1s/2s/4s) con jitter; si persiste, reduzca la presión de envío. |
| 500 | internal_error | Error transitorio del proveedor o fallo interno de procesamiento. | Registre el request id y active el flujo de reintentos. | Reintente de 2 a 3 veces con intervalos cortos; escale si el problema persiste. |
FAQ
- ¿Cuándo debo usar suno?
Úselo para validar conceptos de vídeo rápidamente, comparar el comportamiento de los modos y converger prompts antes del despliegue de la API. - ¿Cómo elijo entre Text-to-Video e Image-to-Video?
Use Text-to-Video cuando solo tenga instrucciones; use Image-to-Video cuando ya disponga de fotogramas clave o composición. - ¿Cuál es la diferencia entre R2V y Video Edit?
R2V se centra en la generación guiada por referencias, mientras que Video Edit se centra en modificar recursos de vídeo existentes. - Error del modelo de imagen o vídeo: invalid apitype: -1
Normalmente esto indica que la solicitud se envió a un endpoint incorrecto. Los modelos de imagen y vídeo no suelen usar el endpoint de chat. En su lugar, envía la solicitud HTTP de tarea que indica la documentación y consulta el endpoint de estado de la tarea para obtener el resultado. Revisa primero el código real de la solicitud, la URL y el payload. - Una tarea de imagen o vídeo falló, pero el usuario fue cobrado igualmente
Pide primero al usuario el registro de la tarea o una captura y comprueba si aparece consumo de tokens de entrada o salida. Si hay registro de tokens, lo más probable es que la solicitud se enviara por un endpoint de chat en lugar del flujo multimedia correcto. Los modelos de imagen y vídeo suelen funcionar como API HTTP de tareas asíncronas: primero se envía la tarea y luego se consulta por task id según la documentación correspondiente.







