---
title: Herramientas MCP
description: Parámetros de las 10 herramientas básicas y las 5 opcionales de Clipia MCP, modelos predeterminados, slugs con barra y las siete auxiliares exclusivas de la aplicación que hay detrás de las tarjetas de resultados.
icon: Wrench
---
Clipia MCP ofrece siempre al agente de IA 10 herramientas básicas. `chat`, `generate_scenario`, `compose_video`, `generate_presentation` y `edit_presentation` se añaden cuando las capacidades de producto correspondientes están activadas. Otras siete auxiliares exclusivas de la aplicación controlan las tarjetas interactivas y nunca entran en el contexto del modelo. Cada llamada de generación devuelve su coste en créditos, y `get_balance` muestra el saldo restante.
`generate_image` o `generate_video` inicia una tarea. Si la respuesta aún no es definitiva (estado `IN_QUEUE` o `IN_PROGRESS`), llame a `wait_generation` con el `request_id` devuelto hasta que el estado sea `COMPLETED`, `FAILED` o `CANCELED`. Las imágenes suelen llegar terminadas en una sola llamada; el vídeo tarda de uno a diez minutos en renderizarse.
## Herramientas básicas [#core]
| Herramienta | Finalidad | Parámetros |
| --- | --- | --- |
| `generate_image` | Imagen a partir de texto o edición a partir de imágenes de referencia. Suele devolver el resultado terminado en una sola llamada | `prompt`, `model`, `aspect_ratio`, `resolution`, `num_images`, `image_urls`, `negative_prompt`, `seed`, `input`, `include_preview`, `wait_seconds`, `idempotency_key` |
| `generate_video` | Vídeo a partir de texto o de un fotograma inicial. Devuelve `request_id` y el coste de inmediato | `prompt`, `model`, `duration`, `aspect_ratio`, `resolution`, `image_url`, `end_image_url`, `image_urls`, `video_url`, `audio_url`, `reference_video_urls`, `generate_audio`, `negative_prompt`, `seed`, `input`, `wait_seconds`, `idempotency_key` |
| `generate_audio` | Texto a voz con la voz elegida. Devuelve un archivo de audio al terminar (mp3 o wav, según el modelo) | `text`, `model`, `voice`, `language`, `stability`, `secondary_voice`, `similarity`, `previous_text`, `input`, `wait_seconds`, `idempotency_key` |
| `generate_music` | Música de fondo o banda sonora a partir de una descripción del ambiente, el género y el tempo, o una canción con su propia letra (`lyrics`) | `prompt`, `lyrics`, `style`, `instrumental`, `model`, `input`, `wait_seconds`, `idempotency_key` |
| `wait_generation` | Espera a que termine una tarea, hasta 30 segundos por llamada | `request_id`, `wait_seconds`, `include_preview` |
| `get_generation` | Estado y resultado al instante: una vista previa y un `original_url` en calidad completa | `request_id`, `include_preview` |
| `list_models` | Catálogo de modelos: slug, tipo, capacidades, precio en créditos. Se devuelve por páginas | `type`, `search`, `limit`, `offset` |
| `get_model` | Esquema de parámetros (`input_schema`) y precio de un modelo | `model` |
| `get_balance` | Saldo de créditos, número de llamadas a la API y gasto de los últimos 30 días | — |
| `search_templates` | Búsqueda entre más de 3500 prompts seleccionados en ruso e inglés | `query`, `media_type`, `limit` |
Parámetros obligatorios: `prompt` para `generate_image` y `generate_music`; `text` para `generate_audio`; `request_id` para `wait_generation` y `get_generation`; `model` para `get_model`; `query` para `search_templates`.
### Límites de los parámetros [#limits]
| Parámetro | Herramienta | Valores |
| --- | --- | --- |
| `num_images` | `generate_image` | de 1 a 4, según el modelo |
| `image_urls` | `generate_image` | matriz de hasta 4 URL https públicas de referencia |
| `image_url` | `generate_video` | una URL https del fotograma inicial; cambia el modelo predeterminado a imagen a vídeo |
| `wait_seconds` | `generate_image`, `generate_audio`, `generate_music` | de 0 a 25, 20 por defecto |
| `wait_seconds` | `generate_video` | de 0 a 25, 0 por defecto |
| `wait_seconds` | `wait_generation` | de 1 a 30, 25 por defecto |
| `include_preview` | `generate_image`, `wait_generation`, `get_generation` | `true` por defecto |
| `stability`, `similarity` | `generate_audio` | de 0 a 1, si el modelo lo admite |
| `previous_text` | `generate_audio` | hasta 100 caracteres del texto anterior para dar continuidad |
| `prompt` | `generate_video` | obligatorio para texto a vídeo; opcional cuando la llamada incluye medios de entrada (lip-sync, motion control) |
| `end_image_url` | `generate_video` | una URL https del último fotograma; funciona en cualquier modelo que admita último fotograma |
| `instrumental` | `generate_music` | `true` por defecto: sin voz; `false` cuando se indica `lyrics` |
| `lyrics`, `style` | `generate_music` | su propia letra y el estilo; el servidor comprueba la longitud permitida |
| `type` | `list_models` | `text`, `image`, `video` o `audio` |
| `limit` | `list_models` | de 1 a 100, 50 por defecto |
| `offset` | `list_models` | desde 0, 0 por defecto: cuántos modelos omitir |
| `media_type` | `search_templates` | `image` o `video` |
| `limit` | `search_templates` | de 1 a 20, 8 por defecto |
`input` transmite parámetros adicionales propios del modelo, tomados de su `input_schema` (consulte `get_model`). Se combinan con los campos de nivel superior.
## Modelos predeterminados [#defaults]
Si omite `model`, el servidor elige uno. A octubre de 2026, los modelos predeterminados son:
| Herramienta | Modelo predeterminado |
| --- | --- |
| `generate_image` | `nano-banana-2` |
| `generate_video` | `seedance-2-fast-t2v`, o `seedance-2-fast-i2v` cuando se indica `image_url` |
| `generate_audio` | `gemini-3-1-flash-tts` |
| `generate_music` | `suno-v6` |
El modelo predeterminado de `chat` y `generate_scenario` puede cambiar: si el resultado es importante, indique `model` de forma explícita, elegido en `list_models` con `type: "text"`. El modelo realmente utilizado y el coste se devuelven en la respuesta de la herramienta.
## Slugs con barra [#mcp-only-models]
`generate_image` y `generate_video` aceptan slugs que contienen una barra: `google/imagen4`, `google/imagen4-fast`, `google/imagen4-ultra`, `grok-imagine/text-to-image`, `grok-imagine/image-to-image`, `midjourney/v7`, `grok-imagine/text-to-video`, `grok-imagine/image-to-video`, `midjourney/v7-image-to-video`. La API REST acepta los mismos slugs; consulte el [Catálogo de modelos](/es/docs/api-reference/models#mcp-only).
## Herramientas dependientes de capacidades [#conditional]
| Herramienta | Finalidad | Parámetros | Disponible cuando |
| --- | --- | --- | --- |
| `chat` | Llama a un modelo de texto: respuesta, uso de tokens y coste en créditos | `model`, `prompt` o `messages` (roles `system`, `user`, `assistant`), `max_tokens`, `temperature`, `response_format` (`text`, `json_object`, `json_schema`), `idempotency_key` (hasta 255 caracteres) | AI Gateway está activado |
| `generate_scenario` | Divide un briefing de vídeo en escenas con prompts en inglés y duraciones, además de un prompt para la banda sonora | `prompt` (obligatorio), `duration_seconds` (10–120, 30 por defecto), `scene_count` (2–12), `aspect_ratio` (`9:16`, `16:9`, `1:1`), `style`, `model` | AI Gateway está activado |
| `compose_video` | Une de 2 a 20 escenas de vídeo terminadas en un solo clip con banda sonora, locución y subtítulos | `scenes` (obligatorio, 2–20), `audio_request_id` o `audio_url`, `voiceover_request_id` o `voiceover_url`, `subtitles` (hasta 100), `aspect_ratio` (`9:16`, `16:9`, `1:1`), `resolution` (`720p`, `1080p`), `normalize`, `idempotency_key` (8–128 caracteres) | La composición en el servidor está activada |
| `generate_presentation` | Crea una presentación: PPTX editable, PDF y vistas previas PNG de las diapositivas | `title` (obligatorio, hasta 120 caracteres), `slides` (obligatorio, 3–20), `language` (`ru`, `en`), `theme`, `brand` | Las presentaciones están activadas |
| `edit_presentation` | Modifica una presentación existente reutilizando las ilustraciones que no cambian | `work_id` (por defecto, la última presentación terminada), `title`, `language`, `theme`, `slides` (operaciones `set`, `insert`, `delete`, `move`), `regenerate_images`, `regenerate_all_images` | Las presentaciones están activadas |
Las tareas de composición tienen un `request_id` que empieza por `cmp_`, y las de presentaciones, por `prs_`. Espérelas con el mismo `wait_generation`.
## Auxiliares exclusivas de la aplicación [#app-only]
Estas siete auxiliares controlan las tarjetas interactivas de resultados, de repetición y de composición en los clientes que pueden mostrarlas. Están ocultas para el modelo y no ocupan el contexto del agente. No necesita llamarlas desde su propio código.
| Herramienta | Finalidad |
| --- | --- |
| `app_get_generation` | Estado de una generación para una tarjeta en vivo |
| `app_get_generations` | Estado de varias tarjetas en una sola solicitud |
| `app_get_rerun_options` | Opciones para repetir una generación terminada |
| `app_rerun_generation` | Repite una generación desde una tarjeta tras una acción explícita del usuario |
| `app_get_compose_editor` | Estado del editor de composición |
| `app_recompose_video` | Vuelve a montar un vídeo compuesto tras un cambio explícito |
| `app_report_event` | Eventos de renderizado de la tarjeta y de apertura del original |
## Un parámetro que el modelo no conoce [#unsupported-parameters]
`generate_image`, `generate_video`, `generate_audio` y `generate_music` rechazan la llamada antes de iniciar la generación cuando `input` o los argumentos de nivel superior contienen un nombre mal escrito, o un parámetro que se sabe que el modelo elegido no aplica; por ejemplo, `seed` o `negative_prompt` en un modelo que no los declara. No se crea ninguna generación ni se reservan créditos. El error `invalid_request` nombra los parámetros rechazados y enumera los que el modelo declara:
```text
Unsupported parameters for model "nano-banana-2": negative_prompt, seed. Parameters declared by this model: aspect_ratio, prompt, resolution. Call get_model with model "nano-banana-2" for types and allowed values, then retry without the unsupported parameters. The generation was not started.
```
Al agente le basta con quitar los parámetros indicados, o consultar sus nombres y valores exactos en `get_model`, y repetir la llamada. Las llamadas con parámetros de `get_model` y las llamadas con valores predeterminados funcionan como antes; una clave de prueba se comporta igual que una de producción. En el mismo caso, la API REST acepta la solicitud y enumera esos parámetros en `warnings`; consulte [Enviar una generación](/es/docs/api-reference/submit#warnings).
## Detalles [#details]
**generate_image** — texto a imagen e imagen a imagen a partir de las referencias de `image_urls`. `num_images` hasta 4 devuelve varias variantes en un único mosaico. Indique `seed` para obtener resultados repetibles solo en los modelos que lo declaran (consulte `get_model`): el modelo predeterminado no lo declara y rechaza la llamada. Las llamadas idénticas en unos 20 segundos se fusionan en una sola generación; para obtener variantes con llamadas separadas, dé a cada una su propio `idempotency_key`.
**generate_video** — texto a vídeo e imagen a vídeo; `image_url` cambia el modelo predeterminado a I2V. Una llamada renderiza un clip: para obtener varias variantes, haga llamadas separadas con un `idempotency_key` distinto cada una (en los modelos que declaran `seed`, como el predeterminado, también sirve un `seed` distinto). Los parámetros del modelo que devuelve `get_model` (`input_schema.parameters`) se pasan en `input`; algunos (por ejemplo `sound`, `mode`, `speed`, `audio`, `multi_shots`) cambian el coste de la llamada. En los modelos de motion control, el vídeo guía de `video_url` determina la duración del clip y el coste: el servidor lo mide y `duration` no influye en el coste. Con `reference_video_urls`, a la duración del resultado se suman los segundos de cada referencia medidos por el servidor.
**generate_audio** — texto a voz. `get_model` devuelve en `text_limits` la longitud de texto admitida por el modelo; un texto más largo se rechaza con un 400 antes de cobrar nada, así que divídalo en partes. Tras `COMPLETED`, el archivo está en `output.audio.url`, su formato (mp3 o wav, según el modelo) en `output.audio.format`, y el `request_id` puede pasarse como `voiceover_request_id` a `compose_video`.
**generate_music** — música a partir de una descripción de texto. Sin voz por defecto, por lo que encaja bien bajo una locución; con `lyrics` se obtiene una canción con su propia letra. Al terminar, el MP3 está en `output.audio.url`; la música suele requerir consultar el estado con `wait_generation`.
**wait_generation** — espera hasta `wait_seconds` a que termine la tarea y devuelve su estado actual. Vuelva a llamarla hasta que el estado sea definitivo. Si el servidor tuvo que apartarse de la solicitud al ejecutarla, las respuestas de `wait_generation` y `get_generation` incluyen un array `warnings`; por ejemplo `audio_dropped`: la pista de audio no superó la comprobación de seguridad del modelo, el vídeo se genera sin sonido y el coste no cambia. El campo se omite cuando no hay nada que avisar.
**get_generation** — una instantánea del estado y del resultado sin esperar: una vista previa optimizada y un `original_url` para descargar en calidad completa.
**list_models** / **get_model** — el catálogo de modelos con precios y capacidades, y el esquema detallado de parámetros de un modelo. Los modelos de texto se cobran por cada 1000 tokens de entrada y de salida. `list_models` devuelve una página del catálogo: `total` es el número de modelos que cumplen los filtros y `truncated: true` indica que la página no los contiene todos. Acote la lista con `type` o `search`, o solicite la página siguiente pasando en `offset` el valor de `next_offset` de la respuesta.
**get_balance** — el saldo de créditos de la cuenta conectada, el número de llamadas a la API y el gasto de los últimos 30 días. Algunas aplicaciones cliente no muestran esta herramienta.
**search_templates** — búsqueda híbrida (texto completo y semántica) en la biblioteca de prompts listos para usar. Cada resultado incluye un prompt listo y un modelo recomendado.
Los modelos de vídeo funcionan mejor con prompts en inglés; para las imágenes también sirve el ruso. No incluya texto en pantalla en un prompt de vídeo, ya que se renderiza con artefactos; añada los rótulos al componer el vídeo con `subtitles`. Para una cámara fija, añada "static locked camera, no zoom, no pan".
Una clave con el prefijo `clipia_test_` cambia las herramientas al modo de prueba: `generate_image` y `generate_video` devuelven al instante un resultado predefinido y no se cobran créditos. Resulta útil para depurar la consulta del estado y el análisis de respuestas en CI. Utilice una clave `clipia_live_` para las generaciones reales.
La dirección del servidor y la configuración de los clientes están en la página [Clipia MCP](/es/docs/mcp).