Zoromi pour agents IA

Que fait Zoromi pour agents IA ?

Zoromi (https://zoromi.studio) transforme une histoire ou une idée en un livre illustré ou une courte vidéo (script, plans, voix, musique et clips), et gère un théâtre de courts drames. Cette compétence vous permet de répondre aux questions sur les prix, les forfaits et le compte de l'utilisateur, et de créer une image ou un clip vidéo pour l'utilisateur, en appelant l'API Zoromi.

Réponses champ par champ pour chaque outil : references/tools.md.

Ce qui est ouvert

Le serveur ouvre ses outils par étapes. Avant de proposer quoi que ce soit, appelez tools/list et utilisez uniquement les outils qu'il liste.

• Toujours ouvert, sans clé : get_zoromi_overview, get_video_prices et get_plans_and_pricing.
• Quand tools/list les montre : les outils qui lisent un compte (solde, livres, projets, tâches, frais) et les outils qui créent quelque chose. Un outil pas encore ouvert répond « Cet outil n'est pas encore ouvert. »

Tant que tools/list ne montre que les trois outils ouverts :

• Ne demandez pas de clé API à l'utilisateur et ne l'envoyez pas en créer une. Les membres ne peuvent pas encore créer de clé.
• Si l'utilisateur demande des informations sur son propre compte, ou souhaite créer une image, une vidéo ou un drame à partir d'ici, dites clairement que ce n'est pas encore ouvert depuis un assistant, et donnez-lui le lien du site web depuis get_zoromi_overview : il peut le faire là-bas dès aujourd'hui.
• Répondez aux questions sur les prix et les forfaits comme d'habitude.

Les sections ci-dessous sur les clés, les outils de compte et la création d'une image ou d'un clip s'appliquent une fois que tools/list montre ces outils.

Règles

1. Ne citez jamais un prix de mémoire. Les prix changent. Appelez estimate_website_clips_cost (avec une clé), get_video_prices ou get_plans_and_pricing à chaque fois et citez ce qu'ils renvoient, avec le lien de la page de tarification qu'ils renvoient.
2. Ne dépensez qu'après que l'utilisateur a dit oui au prix exact. Seuls create_image, create_video_clip et edit_image dépensent, et ils sont payés en dollars américains depuis le solde API du compte, qui est distinct de ses Gems. Obtenez un devis avec estimate_image_cost, estimate_video_clip_cost ou estimate_image_edit_cost, dites à l'utilisateur ce qui sera créé et son coût (price), et attendez un oui clair. Définissez confirmed_by_user à true seulement alors, jamais de votre propre chef. Envoyez exactement les arguments du devis. Si le prix a changé ou si le devis a expiré, faites un nouveau devis et demandez à nouveau. Ne lancez jamais la même tâche deux fois : après start_unknown, vérifiez list_my_gems_charges et list_my_video_projects d'abord. Un clip peut commencer à partir d'une des propres images de l'utilisateur sur Zoromi (first_frame, son id ou son adresse sur Zoromi), seulement après que l'utilisateur a dit oui à « Toutes les personnes montrées dans cette image ont accepté son utilisation » (people_consent) et « J'ai le droit d'utiliser cette image » (rights_confirmed) : demandez-leur, ne le présumez jamais. Les livres, les images créées à partir des propres images de l'utilisateur et les drames entiers sont réalisés sur le site web pour l'instant : donnez à l'utilisateur le lien de get_zoromi_overview. Quand un outil répond content_not_allowed, la politique de contenu n'autorise pas la demande : dites-le à l'utilisateur, et ne reformulez pas pour contourner la politique.
3. Gardez la clé API secrète. Lisez-la depuis la variable d'environnement ZOROMI_API_KEY. Ne l' affichez jamais, ne l'échoïsez pas, ne l'écrivez pas dans un fichier du projet, ne la mettez pas dans un commit, et ne la collez pas dans le chat. Envoyez-la uniquement à zoromi.studio.
4. Vérifiez la réponse, pas le statut HTTP. Un outil peut répondre HTTP 200 et quand même signaler un problème : lisez result.isError avant result.structuredContent. Voir Erreurs.
5. Utilisez les liens que les outils renvoient (page de tarification, page de compte, open_url d'un livre) au lieu d'inventer des URL.
6. Écrivez à l'utilisateur en mots simples. Les Gems sont les crédits de Zoromi sur le site web ; le solde API est en dollars américains. Une réponse comme « 3 segments sur 10 sont filmés » est meilleure que des noms de champs bruts.

Configuration

La clé API

Sautez cette section tant que les outils de compte ne sont pas ouverts (voir Ce qui est ouvert).

Les prix, les forfaits et get_zoromi_overview n'ont pas besoin de clé. Tout ce qui concerne un compte a besoin de la clé du propriétaire de ce compte, qui commence par zk_live_. Le propriétaire la crée sur sa page de compte Zoromi (get_zoromi_overview renvoie le lien). Si l'utilisateur n'a pas encore de clé, répondez à ce que vous pouvez sans une et dites-lui où la créer.

L'utilisateur la définit une fois, en dehors du projet :

# macOS / Linux : ajoutez à ~/.zshrc ou ~/.bashrc
export ZOROMI_API_KEY='zk_live_...'

# Windows PowerShell (utilisateur actuel, persistant)
[Environment]::SetEnvironmentVariable('ZOROMI_API_KEY', 'zk_live_...', 'User')

Si une commande montre que ZOROMI_API_KEY est vide, demandez à l'utilisateur de la définir ; ne lui demandez pas de coller la clé dans le chat.

Option A : se connecter comme serveur MCP (Claude Code et autres clients MCP)

L'API est un serveur MCP sur Streamable HTTP à https://zoromi.studio/api/v1/mcp/skill. Dans Claude Code, mettez ceci dans le .mcp.json du projet. La clé reste dans l'environnement : Claude Code remplit ${ZOROMI_API_KEY} quand il se connecte, donc le fichier ne contient aucun secret.

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

Les outils apparaissent alors par leur nom (get_video_prices etc.) et vous les appelez directement.

Option B : l'appeler avec curl (tout agent)

Chaque appel est une seule requête HTTP POST d'un message JSON-RPC tools/call. Il n'y a pas de session et pas de poignée de main à faire d'abord. Cette fonction shell rend chaque appel en une ligne. Elle envoie la clé via l'entrée standard (-H @-), donc la clé n'apparaît jamais dans la ligne de commande ou la liste des processus.

# usage : zoromi <nom_outil> ['<arguments json>']
zoromi() {
  tool=${1:?usage: zoromi <nom_outil> [arguments-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}'

• Il a seulement besoin de curl. jq est pratique pour lire les réponses (... | jq .result.structuredContent) mais pas nécessaire.
• Windows : exécutez-le dans Git Bash ou WSL. Dans PowerShell, curl est une autre commande ; utilisez curl.exe et écrivez le corps dans un fichier (--data-binary "@body.json") pour éviter les problèmes de guillemets.
• Pour lister chaque outil avec son schéma d'arguments : envoyez {"jsonrpc":"2.0","id":1,"method":"tools/list"} de la même manière.

Outils

Outil	Clé	Arguments	Ce qu'il répond
get_zoromi_overview	non	aucun	Ce que Zoromi crée, comment commencer, liens (site web, inscription, tarification, compte)
get_video_prices	non	aucun	Gems en direct par clip de 5 secondes avec son, par modèle et résolution, et toute réduction en cours
get_plans_and_pricing	non	aucun	Forfaits en direct (prix mensuel / annuel, Gems accordés), paiement à l'utilisation, packs de Gems
get_my_account	oui	aucun	Forfait, solde Gems, plafond journalier d'aujourd'hui, dépensé et restant aujourd'hui
list_my_books	oui	limit 1-100, offset, query	Les livres illustrés de l'utilisateur, du plus récent au plus ancien
get_book	oui	book_id	Un livre : statut et statut de chaque page, image et texte d'ouverture
list_my_video_projects	oui	limit 1-100, offset	Les projets vidéo de l'utilisateur, du plus récent au plus ancien, avec les segments comptés par état
get_video_project	oui	project_id	Un projet vidéo et ses segments comptés par état
get_generation_status	oui	task_id	Une tâche de génération : en file d'attente, en cours, terminée ou échouée ; quand terminée, view_url (la propre page de l'utilisateur pour voir et télécharger) et pour une image créée ici, ce qui a été facturé
list_my_gems_charges	oui	limit 1-200	Frais et remboursements Gems récents, du plus récent au plus ancien
estimate_website_clips_cost	oui	model, resolution, seconds_per_clip, clips, aspect_ratio, with_sound	Gems pour le tournage de ce nombre de clips aux prix de ce compte, et si le solde le couvre. Ne dépense rien
estimate_image_cost	clé de dépense	prompt, et optionnellement model, aspect_ratio, quality	Le prix de cette image exacte et un quote_id (de courte durée, utilisé une fois). Ne dépense rien
create_image	clé de dépense	les mêmes, plus quote_id et confirmed_by_user	Crée l'image devisée et facture son prix au solde API ; répond un task_id
estimate_image_edit_cost	clé de dépense	pictures (1-4 des propres images de l'utilisateur sur Zoromi), prompt, people_consent, rights_confirmed, et optionnellement model, aspect_ratio, quality	Le prix de cette modification exacte et un quote_id (de courte durée, utilisé une fois). Ne dépense rien
edit_image	clé de dépense	les mêmes, plus quote_id et confirmed_by_user	Crée la modification devisée et facture son prix au solde API ; répond un task_id
estimate_video_clip_cost	clé de dépense	model, resolution, seconds, prompt, aspect_ratio, with_sound, et avec une image de départ first_frame, people_consent, rights_confirmed	Le prix de ce clip exact et un quote_id (de courte durée, utilisé une fois). Ne dépense rien
create_video_clip	clé de dépense	les mêmes, plus quote_id et confirmed_by_user	Crée le clip devisé et facture son prix au solde API ; répond un task_id
estimate_website_story_video_cost	oui	model, resolution, clips, seconds_per_clip, cards, aspect_ratio	Une estimation pour un épisode : tournage plus images. Ne dépense rien
start_website_story_video	clé de dépense	script, et optionnellement title, model, resolution, aspect_ratio, seconds_per_clip, target_minutes, keep_my_writing, dialogue_language	Crée le projet sur le site web à partir du script et répond open_url et les boutons que l'utilisateur y appuie. Ne dépense rien
get_website_story_video_status	oui	project_id	À quelle étape est le drame, clips filmés, le lien du film quand il est prêt, quoi appuyer ensuite

Une « clé de dépense » est une clé que le propriétaire du compte a autorisée à créer des images et des clips sur la page du compte, avec une limite quotidienne en dollars qu'il a choisie. Ce qu'elle crée est payé depuis le solde API du compte, que le propriétaire approvisionne sur la page du compte ; il est distinct des Gems, et ni l'un ne paie pour l'autre. estimate_image_cost, create_image, estimate_image_edit_cost, edit_image, estimate_video_clip_cost et create_video_clip ne sont pas listés pour les autres clés.

Avec une clé, get_video_prices répond avec les prix propres à ce compte, qu'un forfait peut modifier. Sans clé, il répond avec les prix publics.

Demandes courantes

« Combien coûterait un court drame de N clips ? » Avec une clé, appelez estimate_website_clips_cost avec le modèle et la résolution (noms exactement comme get_video_prices les liste), les secondes par clip et le nombre de clips ; un drame vertical a aspect_ratio 9:16, par défaut. Rapportez gems_total, gems_per_clip et enough_gems, et dites ce que dit covers : le tournage des clips est le coût principal, mais les images des personnages, la planification, les voix et la musique sont également facturés, et le site web montre le total exact avant que quoi que ce soit ne soit dépensé. Si le modèle arrondit la longueur, la réponse a seconds_note ; transmettez-la. Sans clé, appelez get_video_prices et estimez le tournage comme le total des secondes fois gems_per_second pour ce modèle et cette résolution, en montrant le calcul.

« Quel forfait devrais-je prendre ? » Appelez get_plans_and_pricing, comparez les Gems que chaque forfait accorde avec l'estimation ci-dessus, et donnez le lien de la page de tarification qu'il renvoie.

« Combien de Gems ai-je ? » get_my_account. Mentionnez aussi le plafond journalier et ce qu'il en reste aujourd'hui quand le compte en a un.

« Ma vidéo est-elle terminée ? » list_my_video_projects, puis get_video_project avec l'id du projet. Rapportez les segments comptés par état. Pour un seul id de tâche que l'utilisateur a déjà, utilisez get_generation_status.

« Où est mon livre ? » list_my_books (utilisez query pour rechercher par titre), puis get_book. Donnez open_url du livre.

« Qu'est-ce que j'ai dépensé ? » list_my_gems_charges. Les frais et remboursements sont en Gems ; additionnez-les pour la période demandée par l'utilisateur et donnez le lien de la page d'utilisation qu'il renvoie.

« Fais-moi une image de … » Avec une clé de dépense :

1. Appelez estimate_image_cost avec le prompt (qui ou quoi, où, la lumière, le style) et, si l'utilisateur l'a demandée, la forme du cadre comme aspect_ratio. Laissez model et quality de côté sauf si l'utilisateur les a demandés.
2. Dites à l'utilisateur ce qui sera créé et son price, et demandez-lui. Si enough_balance est false, dites que le solde API ne le couvre pas et donnez-lui account_page pour l'approvisionner.
3. Après un oui clair, appelez create_image avec les mêmes arguments, le quote_id et confirmed_by_user: true.
4. Vérifiez get_generation_status avec le task_id toutes les 5 secondes ou plus jusqu'à SUCCESS ou FAILURE, puis donnez à l'utilisateur view_url (sa propre page sur Zoromi pour voir et télécharger ; le result_url de l'image aussi quand il y en a un) et ce que dit charge qui a été facturé. Quand une image échoue finalement, ce qui a été facturé est remboursé sur le solde API.

« Modifie cette image … » Avec une clé de dépense :

1. L'image doit être une des propres images de l'utilisateur sur Zoromi : son id, ou l'adresse que Zoromi a donnée pour elle. Une image créée avec create_image fonctionne : passez l'adresse que get_generation_status a répondue quand elle était faite. Les autres adresses web ne sont pas acceptées ; ne téléchargez ni ne récupérez rien vous-même.
2. Demandez à l'utilisateur les deux phrases et envoyez true seulement après un oui clair pour chacune : « Toutes les personnes montrées dans cette image ont accepté son utilisation » (people_consent) et « J'ai le droit d'utiliser cette image » (rights_confirmed). Ne présumez jamais du consentement.
3. Appelez estimate_image_edit_cost avec pictures, prompt, et les champs de consentement. Si visibility n'est pas None ou si pictures contient une image non possédée, l'outil répondra une erreur.
4. Présentez le price, attendez une confirmation, puis appelez edit_image.

« Fais un clip vidéo de … » Avec une clé de dépense :

1. Appelez estimate_video_clip_cost. Pour un clip d'une image, incluez first_frame, et demandez d'abord les consentements people_consent et rights_confirmed.
2. Présentez le price et attendez une confirmation.
3. Appelez create_video_clip.
4. Interrogez get_generation_status jusqu'à ce qu'il soit terminé.

« Lance un drame à partir de mon script … » Avec une clé de dépense, un drame de plusieurs clips ne peut être filmé que sur le site web. Appelez start_website_story_video avec le script (texte libre, ce que l'utilisateur a dit). Laissez dialogue_language vide à moins que l'utilisateur en veuille un spécifiquement. L'outil renvoie open_url, et les boutons que l'utilisateur doit appuyer. Dites à l'utilisateur d'aller voir et de suivre les instructions sur cette page, parce que l'agent ne peut pas appuyer sur ces boutons. Pour suivre, utilisez get_website_story_video_status. L'utilisateur doit également approuver les images des personnages sur le site web avant que la facturation ne commence. Ne lancez pas de nouveau drame si le précédent n'est pas terminé : vérifiez list_my_video_projects d'abord.

Erreurs

Les codes d'erreur standard JSON-RPC et les erreurs result.isError avec un result.content de type text. Une cause fréquente d'échec de création d'image / clip est content_not_allowed (la politique de contenu rejette la demande).

Exigences

• L'agent doit pouvoir faire des requêtes HTTP (curl, fetch, requêtes intégrées à l'agent).
• Pour créer des images ou des clips, l'utilisateur doit avoir une clé de dépense.
• L'agent ne doit pas partager ni exposer la clé API.
• Les prix et les consentements doivent toujours être vérifiés avant toute dépense.