Cómo funciona

El servidor MCP ejecuta cada generación como un trabajo asíncrono: lo inicias y luego consultas hasta que termina. Tu cliente gestiona el polling automáticamente — esta página es para quien construye uno o depura el flujo.

#Flujo canónico de medios

Para cualquier herramienta que reciba un archivo del usuario (edición de imagen, control de movimiento, lip-sync, subtítulos, separación, anuncios):

1. get_upload_url(model_id=X) — devuelve un enlace temporal al navegador. Envíalo al usuario tal cual.
2. El usuario sube en su navegador. Kubeez detecta duración / dimensiones en el cliente y las escribe en la tabla de metadatos.
3. get_upload_session(token) — devuelve las URLs públicas más duration_seconds por archivo y un flag billing_readiness (exact / pessimistic_fallback).
4. estimate_generation_cost(model, reference_*_seconds=…) — previsualización exacta del precio sin descontar créditos. Cítaselo al usuario.
5. generate_*(...) — solo después de que el usuario confirme.

Los modelos de tarifa fija (Nano Banana, Flux, Imagen, Z-Image, Seedream, Logo Maker, anuncios, música, voz) saltan el paso 4 — cita cost_per_generation desde get_models directamente.

#Flujos por herramienta

#Imágenes y vídeo

1. Opcional: get_models → elige un model_id y lee sus capacidades.
2. Opcional: get_balance para verificar créditos.
3. generate_media(prompt, model, …) → devuelve generation_id.
4. Consulta get_generation_status(id) cada 5s tras una espera inicial breve (~10s para imagen, ~30s para vídeo corto).
5. Cuando status sea completed, lee outputs[] — cada elemento tiene url, thumbnail_url, opcional optimized_url.

#Música

1. generate_music(prompt, …) → generation_id.
2. Consulta get_music_status(id) tras ~30s, luego cada 5s.
3. Cuando termine, lee songs[] — cada uno con audio_url, stream_url, cover_image_url.

#Subtítulos

1. generate_captions(media_url, …) es síncrono — devuelve subtítulos a nivel de palabra en la respuesta (espera de 1–5 minutos).

#Separación de audio

1. generate_separation(media_url) → separation_id.
2. Consulta get_separation_status(id) tras ~20s, luego cada 5s.
3. Cuando termine, lee vocals_url + instrumental_url.

#Creatividades publicitarias

1. create_ad_copy(reference_ad_url, …, variant_count) → generation_ids: [...] (uno por variante).
2. Consulta cada id con get_generation_status hasta completar.

#Cadencia del polling

Cada fila de get_models lleva un estimated_time_seconds basado en tiempos reales históricos. Úsalo como primera espera de polling, luego cada 5s. No consultes cada segundo — gastas tu cuota de rate-limit por el mismo resultado.

#Buenas prácticas

• Cita el coste antes de generar para cualquier modelo por duración — estimate_generation_cost es de solo lectura.
• Empieza siempre con get_models — no fijes model_ids; las capacidades determinan la forma de la petición.
• Respeta los requisitos de entrada — get_models te dice requires_input_media, max_input_images, etc.
• Maneja 429 (rate limit) — espera y reintenta. No insistas con bucles cerrados ante errores.
• Muestra errores claros al usuario ante créditos insuficientes o entradas inválidas — no reintentes sin acción del usuario.

Consulta Limitaciones para rate limits y comportamiento de devolución de créditos.