Zoromi für KI-Agenten

Was macht Zoromi für KI-Agenten?

Zoromi (https://zoromi.studio) verwandelt eine Geschichte oder eine Idee in ein illustriertes Buch oder ein kurzes Video (Drehbuch, Aufnahmen, Stimmen, Musik und die Clips) und betreibt ein Theater für Kurzdramen. Diese Fertigkeit ermöglicht es dir, Fragen zu Preisen, Plänen und dem eigenen Konto des Nutzers zu beantworten und ein Bild oder einen Videoclip für den Nutzer zu erstellen, indem du die Zoromi-API aufrufst.

Feld-für-Feld-Antworten für jedes Tool: references/tools.md.

Was ist offen

Der Server öffnet seine Tools schrittweise. Bevor du etwas anbietest, rufe tools/list auf und verwende nur die Tools, die es auflistet.

• Immer offen, ohne Schlüssel: get_zoromi_overview, get_video_prices und get_plans_and_pricing.
• Wenn tools/list sie anzeigt: die Tools, die ein Konto auslesen (Guthaben, Bücher, Projekte, Aufträge, Abbuchungen) und die Tools, die etwas erstellen. Ein Tool, das noch nicht geöffnet ist, antwortet mit „Dieses Tool ist noch nicht geöffnet.“

Solange tools/list nur die drei offenen Tools anzeigt:

• Frage den Nutzer nicht nach einem API-Schlüssel und schicke ihn nicht, um einen zu erstellen. Mitglieder können noch keinen Schlüssel erstellen.
• Wenn der Nutzer nach seinem eigenen Konto fragt oder ein Bild, ein Video oder ein Drama von hier aus erstellen möchte, sage klar, dass dies von einem Assistenten aus noch nicht offen ist, und gib ihnen den Website-Link von get_zoromi_overview: Sie können es dort heute tun.
• Beantworte Preis- und Planfragen wie gewohnt.

Die folgenden Abschnitte über Schlüssel, Kontotools und das Erstellen eines Bildes oder Clips gelten, sobald tools/list diese Tools anzeigt.

Regeln

1. Nie einen Preis aus dem Gedächtnis nennen. Preise ändern sich. Rufe jedes Mal estimate_website_clips_cost (mit einem Schlüssel), get_video_prices oder get_plans_and_pricing auf und nenne, was sie zurückgeben, zusammen mit dem Link zur Preisseite, den sie zurückgeben.
2. Gib nur aus, nachdem der Nutzer dem genauen Preis zugestimmt hat. Nur create_image, create_video_clip und edit_image geben Geld aus, und sie werden in US-Dollar vom API-Guthaben des Kontos bezahlt, das getrennt von seinen Gems ist. Hole ein Angebot mit estimate_image_cost, estimate_video_clip_cost oder estimate_image_edit_cost ein, teile dem Nutzer mit, was erstellt wird und was es kostet (price), und warte auf ein klares Ja. Setze confirmed_by_user nur dann auf true, niemals eigenmächtig. Sende genau die angebotenen Argumente. Wenn sich der Preis geändert hat oder das Angebot abgelaufen ist, biete erneut an und frage erneut. Starte niemals denselben Auftrag zweimal: Überprüfe nach start_unknown zuerst list_my_gems_charges und list_my_video_projects. Ein Clip kann von einem der eigenen Bilder des Nutzers auf Zoromi ausgehen (first_frame, seine ID oder seine Adresse auf Zoromi), nur nachdem der Nutzer zugestimmt hat zu „Alle auf diesem Bild gezeigten Personen haben der Verwendung zugestimmt“ (people_consent) und „Ich habe das Recht, dieses Bild zu verwenden“ (rights_confirmed): Frage sie, nimm es nie an. Bücher, Bilder, die aus eigenen Bildern des Nutzers erstellt wurden, und ganze Dramen werden vorerst auf der Website erstellt: Gib dem Nutzer den Link von get_zoromi_overview. Wenn ein Tool mit content_not_allowed antwortet, erlaubt die Inhaltsrichtlinie die Anfrage nicht: teile dem Nutzer dies mit und formuliere es nicht um, um die Richtlinie zu umgehen.
3. Halte den API-Schlüssel geheim. Lese ihn aus der Umgebungsvariable ZOROMI_API_KEY. Gib ihn niemals aus, zeige ihn an, schreibe ihn in eine Datei im Projekt, setze ihn in einen Commit oder füge ihn in den Chat ein. Sende ihn nur an zoromi.studio.
4. Überprüfe die Antwort, nicht den HTTP-Status. Ein Tool kann mit HTTP 200 antworten und trotzdem ein Problem melden: Lese result.isError vor result.structuredContent. Siehe Fehler.
5. Verwende die Links, die die Tools zurückgeben (Preisseite, Kontoseite, open_url eines Buches) anstatt selbst URLs zu erfinden.
6. Schreibe dem Nutzer in einfachen Worten. Gems sind Zoromis Guthaben auf der Website; das API-Guthaben ist in US-Dollar. Eine Antwort wie „3 von 10 Segmenten sind gefilmt“ ist besser als rohe Feldnamen.

Einrichtung

Der API-Schlüssel

Überspringe diesen Abschnitt, während die Kontotools nicht geöffnet sind (siehe Was ist offen).

Preise, Pläne und get_zoromi_overview benötigen keinen Schlüssel. Alles, was ein Konto betrifft, benötigt den Schlüssel des Kontoinhabers, der mit zk_live_ beginnt. Der Inhaber erstellt ihn auf seiner Zoromi-Kontoseite (get_zoromi_overview gibt den Link zurück). Wenn der Nutzer noch keinen Schlüssel hat, beantworte, was du ohne Schlüssel kannst, und teile ihm mit, wo er ihn erstellen kann.

Der Nutzer setzt ihn einmalig außerhalb des Projekts:

# macOS / Linux: zu ~/.zshrc oder ~/.bashrc hinzufügen
export ZOROMI_API_KEY='zk_live_...'

# Windows PowerShell (aktueller Benutzer, persistent)
[Environment]::SetEnvironmentVariable('ZOROMI_API_KEY', 'zk_live_...', 'User')

Wenn ein Befehl anzeigt, dass ZOROMI_API_KEY leer ist, bitte den Nutzer, ihn zu setzen; bitte ihn nicht, den Schlüssel in den Chat einzufügen.

Option A: Als MCP-Server verbinden (Claude Code und andere MCP-Clients)

Die API ist ein MCP-Server über Streamable HTTP unter https://zoromi.studio/api/v1/mcp/skill. Füge in Claude Code Folgendes in die .mcp.json des Projekts ein. Der Schlüssel bleibt in der Umgebung: Claude Code füllt ${ZOROMI_API_KEY} beim Verbinden ein, sodass die Datei kein Geheimnis enthält.

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

Die Tools erscheinen dann mit ihrem Namen (get_video_prices usw.) und du rufst sie direkt auf.

Option B: Mit curl aufrufen (beliebiger Agent)

Jeder Aufruf ist ein einzelner HTTP-POST einer JSON-RPC tools/call-Nachricht. Es gibt keine Sitzung und keinen vorherigen Handshake. Diese Shell-Funktion macht jeden Aufruf zu einer Zeile. Sie sendet den Schlüssel über Standard-Eingabe (-H @-), sodass der Schlüssel niemals in der Befehlszeile oder der Prozessliste erscheint.

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

• Es wird nur curl benötigt. jq ist praktisch, um Antworten zu lesen (... | jq .result.structuredContent), aber nicht erforderlich.
• Windows: Führe es in Git Bash oder WSL aus. In PowerShell ist curl ein anderer Befehl; verwende curl.exe und schreibe den Body in eine Datei (--data-binary "@body.json"), um Anführungszeichenprobleme zu vermeiden.
• Um jedes Tool mit seinem Argumentschema aufzulisten: Sende {"jsonrpc":"2.0","id":1,"method":"tools/list"} auf die gleiche Weise.

Tools

Tool	Schlüssel	Argumente	Antwort: Was ist das?
get_zoromi_overview	nein	keine	Was Zoromi macht, wie man startet, Links (Website, Anmeldung, Preise, Konto)
get_video_prices	nein	keine	Live-Gems pro 5-Sekunden-Clip mit Ton, pro Modell und Auflösung, sowie eventuelle Rabatte
get_plans_and_pricing	nein	keine	Live-Pläne (monatlicher/jährlicher Preis, gewährte Gems), Pay-as-you-go, Gems-Pakete
get_my_account	ja	keine	Plan, Gems-Guthaben, heutiges Tageslimit, heute ausgegeben und verbleibend
list_my_books	ja	limit 1-100, offset, query	Die illustrierten Bücher des Nutzers, neueste zuerst
get_book	ja	book_id	Ein Buch: Status und Status jeder Seite, Bild und Öffnungstext
list_my_video_projects	ja	limit 1-100, offset	Die Videoprojekte des Nutzers, neueste zuerst, mit nach Status gezählten Segmenten
get_video_project	ja	project_id	Ein Videoprojekt und seine nach Status gezählten Segmente
get_generation_status	ja	task_id	Ein Generierungsauftrag: in Warteschlange, laufend, fertig oder fehlgeschlagen; wenn fertig, view_url (die eigene Seite des Nutzers zum Ansehen und Herunterladen) und bei einem hier erstellten Bild, was berechnet wurde
list_my_gems_charges	ja	limit 1-200	Letzte Gems-Abbuchungen und -Rückerstattungen, neueste zuerst
estimate_website_clips_cost	ja	model, resolution, seconds_per_clip, clips, aspect_ratio, with_sound	Gems zum Filmen dieser Anzahl Clips zu den Preisen dieses Kontos und ob das Guthaben ausreicht. Gibt nichts aus
estimate_image_cost	Spending-Key	prompt und optional model, aspect_ratio, quality	Der Preis genau dieses einen Bildes und eine quote_id (kurzlebig, einmalig verwendbar). Gibt nichts aus
create_image	Spending-Key	dieselben plus quote_id und confirmed_by_user	Erstellt das angebotene Bild und belastet den Preis dem API-Guthaben; antwortet mit einer task_id
estimate_image_edit_cost	Spending-Key	pictures (1-4 der eigenen Bilder des Nutzers auf Zoromi), prompt, people_consent, rights_confirmed und optional model, aspect_ratio, quality	Der Preis genau dieser Bearbeitung und eine quote_id (kurzlebig, einmalig verwendbar). Gibt nichts aus
edit_image	Spending-Key	dieselben plus quote_id und confirmed_by_user	Führt die angebotene Bearbeitung durch und belastet den Preis dem API-Guthaben; antwortet mit einer task_id
estimate_video_clip_cost	Spending-Key	model, resolution, seconds, prompt, aspect_ratio, with_sound und bei einem Startbild first_frame, people_consent, rights_confirmed	Der Preis genau dieses einen Clips und eine quote_id (kurzlebig, einmalig verwendbar). Gibt nichts aus
create_video_clip	Spending-Key	dieselben plus quote_id und confirmed_by_user	Erstellt den angebotenen Clip und belastet den Preis dem API-Guthaben; antwortet mit einer task_id
estimate_website_story_video_cost	ja	model, resolution, clips, seconds_per_clip, cards, aspect_ratio	Eine Schätzung für eine Episode: Filmen plus Bilder. Gibt nichts aus
start_website_story_video	Spending-Key	script und optional title, model, resolution, aspect_ratio, seconds_per_clip, target_minutes, keep_my_writing, dialogue_language	Erstellt das Projekt auf der Website aus dem Skript und antwortet mit open_url und den Schaltflächen, die der Nutzer dort drückt. Gibt nichts aus
get_website_story_video_status	ja	project_id	In welchem Schritt sich das Drama befindet, gefilmte Clips, der Link zum Film, wenn fertig, was als nächstes zu drücken ist

Ein „Spending-Key“ ist ein Schlüssel, den der Kontoinhaber auf der Kontoseite zum Erstellen von Bildern und Clips freigegeben hat, mit einem täglichen Limit in US-Dollar, das er gewählt hat. Die erstellten Inhalte werden vom API-Guthaben des Kontos bezahlt, das der Inhaber auf der Kontoseite auflädt; es ist getrennt von Gems, und keines bezahlt das andere. estimate_image_cost, create_image, estimate_image_edit_cost, edit_image, estimate_video_clip_cost und create_video_clip werden für andere Schlüssel nicht aufgelistet.

Mit einem Schlüssel antwortet get_video_prices mit den eigenen Preisen dieses Kontos, die ein Plan ändern kann. Ohne Schlüssel antwortet es mit den öffentlichen Preisen.

Häufige Anfragen

„Was würde ein Kurzdrama mit N Clips kosten?“ Mit einem Schlüssel: Rufe estimate_website_clips_cost mit dem Modell und der Auflösung auf (Namen genau wie von get_video_prices aufgelistet), den Sekunden pro Clip und der Anzahl der Clips; ein vertikales Drama hat aspect_ratio 9:16, die Voreinstellung. Berichte gems_total, gems_per_clip und enough_gems und sage, was covers sagt: Das Filmen der Clips sind die Hauptkosten, aber Bilder der Charaktere, Planung, Stimmen und Musik werden ebenfalls berechnet, und die Website zeigt den genauen Gesamtbetrag an, bevor etwas ausgegeben wird. Wenn das Modell die Länge rundet, hat die Antwort seconds_note; gib dies weiter. Ohne Schlüssel: Rufe get_video_prices auf und schätze das Filmen als Gesamtsekunden mal gems_per_second für dieses Modell und diese Auflösung, und zeige die Rechnung.

„Welchen Plan soll ich nehmen?“ Rufe get_plans_and_pricing auf, vergleiche die Gems, die jeder Plan gewährt, mit der obigen Schätzung und verlinke die Preisseite, die er zurückgibt.

„Wie viele Gems habe ich?“ get_my_account. Erwähne auch das Tageslimit und was davon heute noch übrig ist, wenn das Konto eines hat.

„Ist mein Video fertig?“ list_my_video_projects, dann get_video_project mit der id des Projekts. Berichte die nach Status gezählten Segmente. Für eine Auftrags-ID, die der Nutzer bereits hat, verwende get_generation_status.

„Wo ist mein Buch?“ list_my_books (verwende query, um nach Titel zu suchen), dann get_book. Gib den open_url des Buches.

„Was habe ich ausgegeben?“ list_my_gems_charges. Abbuchungen und Rückerstattungen sind in Gems; summiere sie für den Zeitraum, nach dem der Nutzer fragt, und verlinke die Nutzungsseite, die es zurückgibt.

„Mach mir ein Bild von …“ Mit einem Spending-Key:

1. Rufe estimate_image_cost mit der Beschreibung auf (wer oder was, wo, das Licht, der Stil) und, falls der Nutzer danach gefragt hat, der Bildform als aspect_ratio. Lasse model und quality weg, es sei denn, der Nutzer hat danach gefragt.
2. Teile dem Nutzer mit, was erstellt wird und sein price, und frage nach. Wenn enough_balance false ist, sage, dass das API-Guthaben nicht ausreicht, und gib ihnen account_page, um es aufzuladen.
3. Nach einem klaren Ja rufe create_image mit denselben Argumenten, der quote_id und confirmed_by_user: true auf.
4. Überprüfe get_generation_status mit der task_id alle 5 Sekunden oder länger, bis SUCCESS oder FAILURE erscheint, und gib dem Nutzer dann view_url (seine eigene Seite auf Zoromi zum Ansehen und Herunterladen; den result_url des Bildes auch, falls vorhanden) und was charge als berechnet angibt. Wenn ein Bild schließlich fehlschlägt, wird der berechnete Betrag dem API-Guthaben zurückerstattet.

„Ändere dieses Bild …“ Mit einem Spending-Key:

1. Das Bild muss eines der eigenen des Nutzers auf Zoromi sein: seine ID oder die Adresse, die Zoromi dafür angegeben hat. Ein mit create_image erstelltes Bild funktioniert: Übergib die Adresse, die get_generation_status geantwortet hat, als es fertig war. Andere Webadressen werden nicht akzeptiert; lade selbst nichts hoch und rufe nichts ab.
2. Frage den Nutzer nach beiden Sätzen und sende true nur nach einem klaren Ja zu jedem: „Alle auf diesem Bild gezeigten Personen haben der Verwendung zugestimmt“ (people_consent) und „Ich habe das Recht, dieses Bild zu verwenden“ (rights_confirmed). Nimm niemals an, dass die Bedingungen erfüllt sind.
3. Dann genauso wie bei „Mach mir ein Bild von …“, aber verwende die estimate_image_edit_cost/ edit_image-Tools. Sende dieselbe Liste von Bild-IDs und/oder Adressen (pictures), die Beschreibung (prompt), die Zustimmungen (people_consent, rights_confirmed) und die optionalen model, aspect_ratio und quality genau in beiden Aufrufen.

„Mach mir einen Videoclip von …“ Mit einem Spending-Key: Genauso wie bei Bildern, aber mit estimate_video_clip_cost/create_video_clip. Gib die model- und resolution-Namen an, die get_video_prices auflistet, zusammen mit der seconds-Anzahl, prompt und aspect_ratio. Wenn der Nutzer Ton wünscht, setze with_sound auf true (die Voreinstellung ist false). Beginne nach Zustimmung zu den Bildrechten von einem eigenen Bild des Nutzers (first_frame, people_consent, rights_confirmed).

Hinweise

• Gems vs. API-Guthaben: Gems sind ein Website-Guthaben, das Pläne gewähren und das man auf der Website kauft. Das API-Guthaben in US-Dollar wird auf der Kontoseite aufgeladen. Ein Konto kann beides haben. Die meisten Tools fragen nach Gems-Salden und -Preisen; die Tools, die Geld ausgeben (create_*), belasten das API-Guthaben. Verwechsle sie nicht.
• Bilder als erster Frame: Nur eines der eigenen Bilder des Nutzers auf Zoromi kann als first_frame eines Clips verwendet werden. Der Nutzer muss bestätigen, dass alle darin gezeigten Personen zugestimmt haben und dass der Nutzer das Recht hat, es zu verwenden.
• Falls der Preis abgelehnt wird oder das Guthaben nicht ausreicht: Sage es dem Nutzer klar und gib den Link zur Kontoseite (account_page). Schlage nicht vor, die Anfrage zu ändern, um sie billiger zu machen – das kann der Nutzer selbst tun, wenn er möchte.
• Benachrichtigungen sind nicht implementiert. Es gibt keine Callbacks oder Server-Sent-Events zum Abonnieren.
• start_website_story_video gibt nichts aus. Es erstellt das Projekt auf der Website aus dem Skript. Der Nutzer schließt es dann dort ab (Figuren besetzen, Aufnahmen überprüfen, veröffentlichen). Die open_url-Antwort führt den Nutzer dorthin. Das Filmen wird bezahlt, wenn der Nutzer auf der Website auf „Filmen“ klickt, und die Website zeigt den genauen Betrag vorher an.
• Kontostatus auf der Website: Die meisten Informationen, die die Tools zurückgeben, sind auch auf der Website sichtbar (account_page). Wenn der Nutzer eine Frage hat, die kein Tool beantwortet, verweise ihn an die Website oder den Support.
• Token: Das Authorization-System erwartet einen Token im Format Bearer <token>. Der Token fungiert als API-Schlüssel und als Spending-Key.

Fehler

Die API folgt dem JSON-RPC-Format. Selbst bei HTTP 200 muss das isError-Feld im result-Objekt überprüft werden.

Beispiel für einen Fehler, den isError abfängt:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": "invalid_api_key",
      "message": "The API key provided is invalid or expired."
    }
  }
}

Häufige Fehlertypen:

Fehler	Bedeutung
invalid_api_key	Der API-Schlüssel ist ungültig, abgelaufen oder wurde widerrufen
insufficient_balance	Das API-Guthaben in US-Dollar reicht nicht aus, um die Anfrage zu bezahlen
daily_limit_reached	Der Spending-Key hat sein tägliches Ausgabenlimit erreicht
content_not_allowed	Die Anfrage entspricht nicht der Inhaltsrichtlinie
quote_expired	Die quote_id ist abgelaufen; bitte erneut ein Angebot einholen
task_not_found	Die task_id existiert nicht oder gehört nicht zu diesem Konto

Überprüfe immer result.isError, bevor du result.structuredContent annimmst.