Zoromi para agentes de IA

¿Qué hace Zoromi para agentes de IA?

Zoromi (https://zoromi.studio) convierte una historia o una idea en un libro ilustrado o un video corto (guion, tomas, voces, música y los clips), y dirige un teatro de miniseries. Este skill te permite responder preguntas sobre precios, planes y la cuenta del usuario, y hacer una imagen o un videoclip para el usuario, llamando a la API de Zoromi.

Respuestas campo por campo para cada herramienta: references/tools.md.

Qué está abierto

El servidor abre sus herramientas por etapas. Antes de ofrecer algo, llama a tools/list y usa solo las herramientas que lista.

• Siempre abiertas, sin clave: get_zoromi_overview, get_video_prices y get_plans_and_pricing.
• Cuando tools/list las muestre: las herramientas que leen una cuenta (saldo, libros, proyectos, trabajos, cargos) y las herramientas que crean algo. Una herramienta que aún no está abierta responde "Esta herramienta aún no está abierta".

Mientras tools/list muestre solo las tres herramientas abiertas:

• No le pidas al usuario una clave API ni lo envíes a crear una. Los miembros aún no pueden crear una clave.
• Si el usuario pregunta sobre su propia cuenta, o quiere una imagen, un video o una miniserie hechos desde aquí, dile claramente que esto no está abierto desde un asistente todavía, y dale el enlace del sitio web de get_zoromi_overview: puede hacerlo allí hoy.
• Responde las preguntas sobre precios y planes como de costumbre.

Las secciones a continuación sobre claves, herramientas de cuenta y cómo hacer una imagen o un clip se aplican una vez que tools/list muestre esas herramientas.

Reglas

1. Nunca cotices un precio de memoria. Los precios cambian. Llama a estimate_website_clips_cost (con una clave), get_video_prices o get_plans_and_pricing cada vez y cotiza lo que devuelven, con el enlace a la página de precios que devuelven.
2. Gasta solo después de que el usuario diga sí al precio exacto. Solo create_image, create_video_clip y edit_image gastan, y se pagan en dólares estadounidenses desde el saldo de API de la cuenta, que es independiente de sus Gems. Obtén un presupuesto con estimate_image_cost, estimate_video_clip_cost o estimate_image_edit_cost, dile al usuario qué crea y cuánto cuesta (price), y espera un sí claro. Establece confirmed_by_user a true solo entonces, nunca por tu cuenta. Envía exactamente los argumentos presupuestados. Si el precio cambió o el presupuesto caducó, presupuesta de nuevo y pregunta de nuevo. Nunca inicies el mismo trabajo dos veces: después de start_unknown, verifica list_my_gems_charges y list_my_video_projects primero. Un clip puede comenzar desde una de las imágenes propias del usuario en Zoromi (first_frame, su id o su dirección en Zoromi), solo después de que el usuario haya dicho sí a "Todas las personas que aparecen en esta imagen aceptaron que se use" (people_consent) y "Tengo derecho a usar esta imagen" (rights_confirmed): pregúntales, nunca lo asumas. Los libros, las imágenes hechas a partir de imágenes propias del usuario y las miniseries completas se hacen en el sitio web por ahora: dale al usuario el enlace de get_zoromi_overview. Cuando una herramienta responda content_not_allowed, la política de contenido no permite la solicitud: díselo al usuario, y no reformules la solicitud para evadir la política.
3. Mantén la clave API en secreto. Léela de la variable de entorno ZOROMI_API_KEY. Nunca la imprimas, la hagas eco, la escribas en un archivo del proyecto, la pongas en un commit, o la pegues en el chat. Envíala solo a zoromi.studio.
4. Verifica la respuesta, no el estado HTTP. Una herramienta puede responder HTTP 200 y aun así informar un problema: lee result.isError antes de result.structuredContent. Consulta Errores.
5. Usa los enlaces que devuelven las herramientas (página de precios, página de cuenta, open_url de un libro) en lugar de inventar URLs.
6. Escribe al usuario en lenguaje sencillo. Los Gems son los créditos de Zoromi en el sitio web; el saldo de API está en dólares estadounidenses. Una respuesta como "3 de 10 segmentos están filmados" es mejor que los nombres de campo sin procesar.

Configuración

La clave API

Omite esta sección mientras las herramientas de cuenta no estén abiertas (consulta Qué está abierto).

Los precios, planes y get_zoromi_overview no necesitan clave. Todo lo relacionado con una cuenta necesita la clave del propietario de esa cuenta, que comienza con zk_live_. El propietario la crea en su página de cuenta de Zoromi (get_zoromi_overview devuelve el enlace). Si el usuario aún no tiene clave, responde lo que puedas sin una y dile dónde crearla.

El usuario la establece una vez, fuera del proyecto:

# macOS / Linux: agregar a ~/.zshrc o ~/.bashrc
export ZOROMI_API_KEY='zk_live_...'

# Windows PowerShell (usuario actual, persiste)
[Environment]::SetEnvironmentVariable('ZOROMI_API_KEY', 'zk_live_...', 'User')

Si un comando muestra que ZOROMI_API_KEY está vacía, pídele al usuario que la configure; no le pidas que pegue la clave en el chat.

Opción A: conectar como servidor MCP (Claude Code y otros clientes MCP)

La API es un servidor MCP sobre HTTP Streamable en https://zoromi.studio/api/v1/mcp/skill. En Claude Code, pon esto en el .mcp.json del proyecto. La clave permanece en el entorno: Claude Code completa ${ZOROMI_API_KEY} cuando se conecta, por lo que el archivo no contiene ningún secreto.

{
  "mcpServers": {
    "zoromi": {
      "type": "http",
      "url": "https://zoromi.studio/api/v1/mcp/skill",
      "headers": { "Authorization": "Bearer ${ZOROMI_API_KEY}" }
    }
  }
}

Las herramientas aparecen entonces por nombre (get_video_prices y así sucesivamente) y las llamas directamente.

Opción B: llamarlo con curl (cualquier agente)

Cada llamada es una POST HTTP de un mensaje JSON-RPC tools/call. No hay sesión ni apretón de manos que hacer primero. Esta función de shell hace cada llamada en una línea. Envía la clave a través de la entrada estándar (-H @-), por lo que la clave nunca aparece en la línea de comandos o en la lista de procesos.

# uso: zoromi <nombre_herramienta> ['<argumentos_json>']
zoromi() {
  tool=${1:?uso: zoromi <nombre_herramienta> [argumentos-json]}
  args=${2:-}; [ -n "$args" ] || args='{}'
  body=$(printf '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"%s","arguments":%s}}' "$tool" "$args")
  url=${ZOROMI_API_URL:-https://zoromi.studio/api/v1/mcp/skill}
  if [ -n "${ZOROMI_API_KEY:-}" ]; then
    printf 'Authorization: Bearer %s\n' "$ZOROMI_API_KEY" |
      curl -sS -X POST "$url" -H 'Content-Type: application/json' \
        -H 'Accept: application/json, text/event-stream' -H @- --data-binary "$body"
  else
    curl -sS -X POST "$url" -H 'Content-Type: application/json' \
      -H 'Accept: application/json, text/event-stream' --data-binary "$body"
  fi
  echo
}

zoromi get_video_prices
zoromi list_my_books '{"limit": 5}'

• Solo necesita curl. jq es útil para leer respuestas (... | jq .result.structuredContent) pero no es obligatorio.
• Windows: ejecútalo en Git Bash o WSL. En PowerShell, curl es otro comando; usa curl.exe y escribe el cuerpo en un archivo (--data-binary "@body.json") para evitar problemas de citas.
• Para listar cada herramienta con su esquema de argumentos: envía {"jsonrpc":"2.0","id":1,"method":"tools/list"} de la misma manera.

Herramientas

Herramienta	Clave	Argumentos	Qué responde
get_zoromi_overview	no	ninguno	Qué hace Zoromi, cómo empezar, enlaces (sitio web, registro, precios, cuenta)
get_video_prices	no	ninguno	Gems en vivo por clip de 5 segundos con sonido, por modelo y resolución, y cualquier descuento actual
get_plans_and_pricing	no	ninguno	Planes en vivo (precio mensual / anual, Gems otorgados), pago por uso, paquetes de Gems
get_my_account	sí	ninguno	Plan, saldo de Gems, límite diario de hoy, gastado y restante hoy
list_my_books	sí	limit 1-100, offset, query	Los libros ilustrados del usuario, los más nuevos primero
get_book	sí	book_id	Un libro: estado y estado de cada página, imagen y texto de apertura
list_my_video_projects	sí	limit 1-100, offset	Los proyectos de video del usuario, los más nuevos primero, con segmentos contados por estado
get_video_project	sí	project_id	Un proyecto de video y sus segmentos contados por estado
get_generation_status	sí	task_id	Un trabajo de generación: en cola, ejecutándose, terminado o fallido; cuando termina, view_url (la página del usuario para verlo y descargarlo) y, para una imagen hecha aquí, lo que se cobró
list_my_gems_charges	sí	limit 1-200	Cargos y reembolsos recientes de Gems, los más nuevos primero
estimate_website_clips_cost	sí	model, resolution, seconds_per_clip, clips, aspect_ratio, with_sound	Gems por filmar esa cantidad de clips a los precios de esta cuenta, y si el saldo lo cubre. No gasta nada
estimate_image_cost	clave de gasto	prompt, y opcionalmente model, aspect_ratio, quality	El precio de exactamente esta imagen y un quote_id (de corta duración, usado una vez). No gasta nada
create_image	clave de gasto	los mismos, más quote_id y confirmed_by_user	Crea la imagen presupuestada y cobra su precio al saldo de API; responde un task_id
estimate_image_edit_cost	clave de gasto	pictures (1-4 de las imágenes propias del usuario en Zoromi), prompt, people_consent, rights_confirmed, y opcionalmente model, aspect_ratio, quality	El precio de exactamente esta edición y un quote_id (de corta duración, usado una vez). No gasta nada
edit_image	clave de gasto	los mismos, más quote_id y confirmed_by_user	Crea la edición presupuestada y cobra su precio al saldo de API; responde un task_id
estimate_video_clip_cost	clave de gasto	model, resolution, seconds, prompt, aspect_ratio, with_sound, y con una imagen para comenzar first_frame, people_consent, rights_confirmed	El precio de exactamente este clip y un quote_id (de corta duración, usado una vez). No gasta nada
create_video_clip	clave de gasto	los mismos, más quote_id y confirmed_by_user	Crea el clip presupuestado y cobra su precio al saldo de API; responde un task_id
estimate_website_story_video_cost	sí	model, resolution, clips, seconds_per_clip, cards, aspect_ratio	Un estimado para un episodio: filmación más imágenes. No gasta nada
start_website_story_video	clave de gasto	script, y opcionalmente title, model, resolution, aspect_ratio, seconds_per_clip, target_minutes, keep_my_writing, dialogue_language	Crea el proyecto en el sitio web desde el guion y responde open_url y los botones que el usuario presiona allí. No gasta nada
get_website_story_video_status	sí	project_id	En qué paso está la miniserie, clips filmados, el enlace de la película cuando esté lista, qué presionar a continuación

Una "clave de gasto" es aquella a la que el propietario de la cuenta permitió hacer imágenes y clips en la página de la cuenta, con un límite diario en dólares que eligió. Lo que crea se paga desde el saldo de API de la cuenta, que el propietario recarga en la página de la cuenta; es independiente de los Gems, y ninguno paga al otro. estimate_image_cost, create_image, estimate_image_edit_cost, edit_image, estimate_video_clip_cost y create_video_clip no están listadas para otras claves.

Con una clave, get_video_prices responde con los precios propios de esa cuenta, que un plan puede cambiar. Sin una clave responde con los precios públicos.

Solicitudes comunes

"¿Cuánto costaría una miniserie de N clips?" Con una clave, llama a estimate_website_clips_cost con el modelo y la resolución (nombres exactamente como los lista get_video_prices), los segundos por clip y la cantidad de clips; una miniserie vertical tiene aspect_ratio 9:16, el valor predeterminado. Informa gems_total, gems_per_clip y enough_gems, y di lo que dice covers: filmar los clips es el costo principal, pero las imágenes de los personajes, la planificación, las voces y la música también se cobran, y el sitio web muestra el total exacto antes de gastar algo. Si el modelo redondea la duración, la respuesta tiene seconds_note; transmítelo. Sin una clave, llama a get_video_prices y estima la filmación como los segundos totales multiplicados por gems_per_second para ese modelo y resolución, mostrando la aritmética.

"¿Qué plan debería elegir?" Llama a get_plans_and_pricing, compara los Gems que otorga cada plan con el estimado anterior, y enlaza la página de precios que devuelve.

"¿Cuántos Gems tengo?" get_my_account. También menciona el límite diario y lo que queda de él hoy cuando la cuenta tenga uno.

"¿Terminó mi video?" list_my_video_projects, luego get_video_project con el id del proyecto. Informa los segmentos contados por estado. Para un id de trabajo que el usuario ya tiene, usa get_generation_status.

"¿Dónde está mi libro?" list_my_books (usa query para buscar por título), luego get_book. Da el open_url del libro.

"¿En qué gasté?" list_my_gems_charges. Los cargos y reembolsos están en Gems; súmalos para el período sobre el que el usuario pregunta y enlaza la página de uso que devuelve.

"Hazme una imagen de ..." Con una clave de gasto:

1. Llama a estimate_image_cost con el prompt (quién o qué, dónde, la luz, el estilo) y, si el usuario lo pidió, la forma del marco como aspect_ratio. Deja fuera model y quality a menos que el usuario lo haya pedido.
2. Dile al usuario lo que se creará y su price, y pregunta. Si enough_balance es false, di que el saldo de API no lo cubre y dale account_page para que agregue fondos.
3. Después de un sí claro, llama a create_image con los mismos argumentos, el quote_id y confirmed_by_user: true.
4. Verifica get_generation_status con el task_id cada 5 segundos o más hasta que sea SUCCESS o FAILURE, luego dale al usuario view_url (su propia página en Zoromi para verla y descargarla; el result_url de la imagen también cuando lo haya) y lo que charge dice que se cobró. Cuando una imagen finalmente falla, lo que se cobró se devuelve al saldo de API.

"Cambia esta imagen ..." Con una clave de gasto:

1. La imagen debe ser una de las imágenes propias del usuario en Zoromi: su id, o la dirección que Zoromi le dio. Una imagen hecha con create_image funciona: pasa la dirección que get_generation_status respondió cuando estuvo terminada. No se aceptan otras direcciones web; no subas ni obtengas nada tú mismo.
2. Pregunta al usuario ambas frases y envía true solo después de un sí claro a cada una: "Todas las personas que aparecen en esta imagen aceptaron que se use" (people_consent) y "Tengo derecho a usar esta imagen" (rights_confirmed).

[truncado para traducción - fin del markdown traducido]