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, P-Video, Gemini Omni) la resolución forma parte del model_id de la variante concreta — pasa la variante (p. ej. seedance-2-fast-480p, p-video-1080p, gemini-omni-video-1080p-6s), 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 tres familias de modelos separadas — seedance-2-fast (económico, rápido), seedance-2 (estándar, mayor calidad) y seedance-2-mini (el más barato, ~50% por debajo de Fast, solo 480p/720p). 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-mini-720p, seedance-2-720p-video-ref) — pasar solo el nombre de familia devuelve un error variant_required con las opciones disponibles. Resoluciones: 480p, 720p o 1080p (ids de variante seedance-2-480p / -720p / -1080p, cada una con su forma -video-ref). 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.

Gemini Omni Video — el modelo multi-modal de Google:

Gemini Omni Video produce salida de vídeo con audio integrado (29 voces nombradas) y acepta entradas multi-modales (texto, referencias de imagen, una referencia de vídeo opcional). El modelo viene en 15 variantes concretas — elige la que coincida con la resolución y duración objetivo. 720p y 1080p tienen precio idéntico; 4K es un nivel de precio separado.

Ids de variante (pasados a generate_media como model):

Las variantes video-ref toman la duración del clip fuente recortado (se usan los primeros 10s; sin parámetros de recorte expuestos). Las variantes basadas en duración aceptan 1–7 referencias de imagen; las variantes video-ref aceptan 1 clip fuente (consume 2 slots) + hasta 5 referencias de imagen.

Tarifa plana por tarea. Tarifas en vivo (720p y 1080p comparten cada fila — Google las factura idénticamente):

Parámetros específicos de Gemini Omni:

Media fuente (source_media_urls): 7 slots de referencia en total. Un único vídeo de referencia consume 2 slots; cada character_id consume 1 slot; las imágenes ocupan el resto. Máximo 1 vídeo por petición; pasar una URL de vídeo requiere una variante -video-ref (variante de duración + vídeo devuelve variant_mismatch). La ventana del clip director es por defecto los primeros 10 segundos; sobrescribe con video_trim_start_s / video_trim_end_s. Las URLs de archivos de audio no se aceptan (devuelve unsupported_audio_url); usa voice_id en su lugar.

Herramientas complementarias (úsalas junto con las generaciones de Gemini Omni):

Ejemplo de petición (1080p, 6s, vertical, reusando un personaje guardado + voz elegida):

{
  "model": "gemini-omni-video-1080p-6s",
  "prompt": "Un barista prepara un espresso perfecto, narrando el proceso",
  "aspect_ratio": "9:16",
  "voice_id": "kore",
  "character_ids": ["char_4f2a9b7c"],
  "source_media_urls": ["https://media.kubeez.com/cafe-shot.jpg"]
}

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, Wan, Grok, Kling 2.5 imagen a vídeo, Motion Control, Gemini Omni Video — este último expone un parámetro voice_id para elegir entre 29 voces built-in).
   • 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.

<a id="trim_video"></a>

#trim_video

Recorta una ventana de cualquier URL de vídeo accesible públicamente y aloja el clip recortado. Kubeez gestiona el recorte server-side y devuelve una url pública que puedes pasar directamente a generate_media como valor de source_media_urls.

Cuándo usar esta herramienta:

• El vídeo fuente del usuario es más largo que el límite del modelo para el clip de referencia y quieres resultados deterministas en lugar de depender de los hints de trim del proveedor.
• Quieres usar una ventana específica de un asset más largo (p. ej. "usa los segundos 5–12, no los primeros 10").
• Encadenas varias generaciones y quieres una única URL canónica recortada reutilizable entre llamadas.

Límites por modelo (sáltate el trim cuando la fuente ya encaja):

Parámetros:

Devuelve: { url, size_bytes, duration_s, start_s, end_s, elapsed_s }. La url es un enlace público alojado en Kubeez que apunta al bucket media-inputs de Supabase storage, seguro para usar como valor de source_media_urls. Los clips recortados conviven con los inputs subidos por el usuario y comparten la misma limpieza automática semanal — trátalos como efímeros, no como un asset permanente.

Flujo típico (Gemini Omni Video con fuente larga del usuario):

1. get_upload_url(model_id="gemini-omni-video-1080p-video-ref")
       → página de upload presignada
2. (el usuario sube su clip de 25s a través del enlace)
3. get_upload_session(token) → { media_urls: ["https://.../source.mp4"] }
4. trim_video(source_url=media_urls[0], start_s=5, end_s=15)
       → { url: "https://.../trims/<uuid>.mp4", duration_s: 10 }
5. generate_media(
       model="gemini-omni-video-1080p-video-ref",
       prompt="...",
       source_media_urls=[<url recortada>]
   )

Trim standalone (URL fuente ya pública — sin paso de upload):

trim_video(source_url="https://media.kubeez.com/<asset>.mp4", start_s=0, end_s=8)
       → { url, duration_s: 8 }
generate_media(model="kling-3-0-motion-control-1080p", source_media_urls=[<imagen>, <url recortada>], ...)

Errores:

Ejemplo de petición:

{
  "source_url": "https://media.kubeez.com/u123/uploads/long-take.mp4",
  "start_s": 5.2,
  "end_s": 14.7
}

Ejemplo de respuesta:

{
  "url": "https://<project>.supabase.co/storage/v1/object/public/media-inputs/u123/trims/abc.mp4",
  "size_bytes": 1245678,
  "duration_s": 9.5,
  "start_s": 5.2,
  "end_s": 14.7,
  "elapsed_s": 1.83
}

Precisión por frame: -c copy alinea el inicio efectivo al keyframe precedente más cercano (desplazamiento ≤ 1 GOP, típicamente ≤ 1s). Comportamiento idéntico al stream-copy MP4 nativo de la web UI. Para cortes precisos por frame, recodifica la fuente previamente — el trade-off es una operación más lenta y con pérdidas, que evitamos deliberadamente aquí.

No conserves el output: la URL apunta al bucket media-inputs que se limpia semanalmente. Si necesitas que el clip recortado sobreviva a la siguiente generación, usa manage_library(kind="asset", action="add", ...) para copiarlo a la Biblioteca de Assets permanente del usuario.

#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).