Herramientas MCP

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.

Herramientas básicas

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

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

Si omite model, el servidor elige uno. A octubre de 2026, los modelos predeterminados son:

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

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.

Herramientas dependientes de capacidades

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

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.

Un parámetro que el modelo no conoce

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:

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.

Detalles

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.

La dirección del servidor y la configuración de los clientes están en la página Clipia MCP.