Herramientas de medios

Genera imágenes y vídeos con más de 40 modelos de IA. Llama siempre primero a get_models para ver modelos disponibles, costes y si un modelo necesita imagen de entrada.

Clientes HTTP REST: los mismos límites están documentados en Requisitos por modelo (API REST) (y devueltos por modelo desde GET /v1/models).

#generate_media

Inicia una generación de imagen o vídeo.

Parámetros:

Ejemplo (texto a imagen):

{
  "prompt": "Ciudad futurista al atardecer con coches voladores",
  "model": "nano-banana",
  "generation_type": "text-to-image",
  "aspect_ratio": "16:9",
  "quality": "pro"
}

Ejemplo (imagen a vídeo, se requiere una imagen):

{
  "prompt": "Movimiento suave y sutil",
  "model": "kling-2-6-image-to-video",
  "generation_type": "image-to-video",
  "source_media_urls": ["https://example.com/your-image.jpg"],
  "aspect_ratio": "16:9",
  "duration": "5s"
}

Respuesta: Incluye generation_id, status (p. ej. pending), y a menudo estimated_time_seconds y estimated_cost_credits. Consulta con get_generation_status hasta que el estado sea completed o failed.

Modelos que admiten duration:

En modelos solo imagen, duration se ignora.

Modelos que admiten negative_prompt:

El resto de modelos ignoran negative_prompt.

Modelos que admiten quality (o equivalente):

En otros modelos, quality se ignora.

<a id="niveles-resolucion"></a>

Niveles de resolución (parámetro resolution):

Cuándo elegir cada nivel (GPT Image 2):

• 1K — predeterminado. Úsalo para publicaciones sociales, miniaturas, conceptos, vistas previas en app, cualquier cosa ≤ 1024 × 1024. El más barato; sin complicaciones de aspect ratio.
• 2K — úsalo cuando el cliente necesita un hero web nítido, portada de newsletter, ilustración in-product a densidad retina. Debes elegir un aspecto direccional (landscape o portrait).
• 4K — úsalo para impresión, publicidad exterior, banners, o cualquier caso en el que el usuario pida explícitamente el tamaño máximo. Confirma el aspecto con el usuario primero; 1:1 / auto no funcionarán.

Los modelos no listados ignoran resolution. Para familias de vídeo (Seedance, Kling, Sora, P-Video) la resolución forma parte del model_id de la variante concreta — pasa la variante (p. ej. seedance-2-fast-480p, p-video-1080p), no este parámetro.

Límites de caracteres del prompt:

Algunos modelos aplican longitud máxima. Superarla puede devolver error o truncar.

Otros pueden no tener límite documentado o usar predeterminados del servidor.

Límites de archivos de entrada (imagen y vídeo):

Para imagen a vídeo e imagen a imagen, source_media_urls es una lista de URLs. La mayoría aceptan solo imágenes (JPEG, PNG, WebP, típicamente 10 MB máx. por archivo). Algunos también aceptan vídeo; entonces aplican formato y tamaño (p. ej. MP4, duración máx.).

Usa get_models para confirmar input_media_types y capacidades. Consulta Herramientas de cuenta para lista y precios.

Kling 3.0 – elementos (opcional):

Los elementos permiten referenciar imágenes o vídeos en el prompt con @element_name. Pasa kling_elements como array de objetos con name, description, y element_input_urls (2–4 URLs de imagen) o element_input_video_urls (1 URL de vídeo). Las imágenes de referencia de cada elemento provienen de su propio element_input_urls; el image_urls principal puede ir vacío para texto-a-vídeo, o contener cuadros de inicio/fin opcionales para imagen-a-vídeo. Cada elemento requiere título (name) y descripción. Elementos imagen: JPG/PNG, mín. 300×300px, máx. 10MB cada uno. Elementos vídeo: MP4/MOV, máx. 50MB.

Seedance 1.5 Pro – dos modos (revisa generation_type antes de usar imágenes):

Seedance 2 – dos familias de modelo, dos modos, dos vías de facturación:

Seedance 2 (ByteDance) se expone como dos familias de modelos separadas — seedance-2-fast (económico, rápido) y seedance-2 (estándar, mayor calidad). Cada familia expone model_ids concretos por resolución y combinación con vídeo de referencia; pasa la variante completa (p. ej. seedance-2-fast-480p, seedance-2-720p-video-ref) — pasar solo el nombre de familia devuelve un error variant_required con las opciones disponibles. Resoluciones: 480p y 720p (no hay 1080p). Duración: entero de 4 a 15 segundos. Aspect ratios admitidos: 1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive. Máximo de prompt: 2500 caracteres. El audio se activa con el toggle gratuito generate_audio (por defecto true) — a diferencia de Kling 3.0, no hay recargo por audio.

Modos:

En ambos modos, mete todas las URLs de referencia en source_media_urls. El backend clasifica cada URL por extensión (.jpg/.png/.webp → imagen; .mp4/.mov/.webm → vídeo; .mp3/.wav/.m4a → audio) y la enruta al cubo correcto automáticamente.

Vías de facturación (importante):

• Sin vídeo de referencia: credits = output_s × base_credits/s
• Con vídeo de referencia (vía proveedor upstream): credits = (ref_s + output_s) × base_credits/s, donde ref_s es la duración combinada de todos los vídeos de referencia, limitada a 15 segundos por petición.

Nota para usuarios de API REST / MCP: el backend no puede consultar remotamente la duración de un vídeo desde su URL, así que factura en el peor caso pesimista (15s) para peticiones con vídeo de referencia enviadas desde MCP o la API REST. La web UI mide localmente y factura las duraciones exactas — si trabajas con clips de referencia cortos y quieres optimizar coste, recomendamos usar la web UI.

Tarifas por segundo en vivo (extraídas del catálogo ai_models_config — siempre al día):

Límites estrictos (se aplican con errores 400):

• Más de 3 vídeos de referencia → too_many_videos.
• Más de 3 audios de referencia → too_many_audios.
• Más de 9 imágenes de referencia → too_many_images.
• Duración combinada de vídeos de referencia > 15s → rechazado.
• Duración combinada de audios de referencia > 15s → rechazado.
• Cualquier archivo individual de vídeo o audio de referencia > 15s → rechazado.

Audio en vídeo (dos conceptos):

1. capabilities.video_audio en get_models — si la salida hay sonido:
   • included — la salida suele incluir pista de audio sin el parámetro sound (p. ej. Veo, Sora, Wan, Grok, Kling 2.5 imagen a vídeo, Motion Control).
   • toggle_via_sound_param — el audio generado se activa/desactiva con sound: true / false (Kling 2.6, Kling 3.0, Seedance 1.5 Pro). El precio puede variar. Kling 3.0 enruta sound: true a filas dedicadas -audio en el catálogo — tú sigues usando kling-3-0-std / kling-3-0-pro como model id y solo cambias sound; el servidor escoge la fila con la tarifa correcta. Tarifas en vivo:

Tarifas por segundo de Motion Control (Kling 3.0 y Kling 2.6):

• silent — sin audio generado (solo Seedance 1.0 / v1-pro-fast-i2v).

2. supports_sound — solo indica que la API acepta el conmutador sound en ese modelo; no significa que el resto de vídeo vaya sin sonido; la mayoría tienen video_audio: included.

Los modelos solo imagen ignoran sound.

#API REST: URLs para archivos locales o del navegador

Si usas la API HTTP (POST /v1/generate/media) y tus entradas son archivos en disco o seleccionados en el navegador — aún no son URLs públicas — sube cada archivo primero con POST /v1/upload/media. Pasa los valores urls devueltos como source_media_urls.

#get_generation_status

Comprueba el estado de una generación de medios y obtén URLs de salida al terminar.

Parámetros:

Respuesta: Incluye status (pending, queued, processing, completed, failed), progress, y al completarse un array outputs con url, thumbnail_url, optimized_url, media_type, dimensiones, etc.

#get_generation_estimate

Obtiene un tiempo de procesamiento estimado según parámetros (no se inicia ningún trabajo). Para duración estimada por modelo en una sola llamada, usa get_models; cada modelo incluye estimated_time_seconds. Usa get_generation_estimate cuando la estimación dependa de longitud del prompt, duration u otros parámetros.

Parámetros:

Respuesta: Tiempo estimado (y opcionalmente confianza/tamaño de muestra) para fijar expectativas antes de llamar a generate_media.

#Reglas de modelo

• Texto a imagen y texto a vídeo: No envíes source_media_urls (salvo que el modelo admita imagen de referencia opcional). Excepción: seedance-1-5-pro en modo texto a vídeo acepta 0–1 imágenes opcionales.
• Imagen a vídeo e imagen a imagen: Envía URL(s) de imagen (y cuando corresponda, vídeo) en source_media_urls. La mayoría necesitan solo imágenes; algunos (p. ej. Kling 2.6 Motion Control) requieren 1 imagen + 1 vídeo. seedance-1-5-pro en imagen a vídeo exige exactamente 2 imágenes (inicio + fin). Respeta los límites de cada modelo.
• Audio en vídeo: Usa capabilities.video_audio de get_models. included — audio sin el parámetro sound. toggle_via_sound_param — usa sound solo si supports_sound es true. silent — sin audio generado (solo Seedance 1.0). No infieras «sin audio» solo por supports_sound: false.
• Usa get_models para ver qué modelos admiten qué tipos de generación, input_media_types (p. ej. image, video) y recuentos de entrada obligatorios.

Consulta Limitaciones para límites de ritmo y créditos. Para una sola tabla de predeterminados API (máx. prompt, entradas, duración, banderas), consulta Requisitos por modelo (API REST).