AIエージェントのためのZoromi
Zoromi（https://zoromi.studio）は、ストーリーやアイデアをイラストブックや短編動画（スクリプト、ショット、音声、音楽、クリップ）に変換し、短編ドラマの劇場を運営します。このスキルを使用すると、Zoromi APIを呼び出して、価格、プラン、ユーザー自身のアカウントに関する質問に答え、ユーザーのために1枚の画像または1つの動画クリップを制作できます。
各ツールのフィールドごとの回答：references/tools.md
開放されているもの
サーバーは段階的にツールを開放します。何かを提供する前に、tools/listを呼び出し、リストされているツールのみを使用してください。
- 常に開放、キー不要：
get_zoromi_overview、get_video_prices、get_plans_and_pricing tools/listに表示された場合： アカウントを読み取るツール（残高、本、プロジェクト、ジョブ、チャージ）と、何かを制作するツール。まだ開放されていないツールは「このツールはまだ開放されていません」と応答します。
tools/listに3つの開放されたツールのみが表示されている間：
- ユーザーにAPIキーを求めたり、作成するように誘導したりしないでください。メンバーはまだキーを作成できません。
- ユーザーが自分のアカウントについて尋ねたり、ここから画像、動画、ドラマの制作を希望したりした場合は、アシスタントからはまだ開放されていないことを明確に伝え、
get_zoromi_overviewからウェブサイトのリンクを提供してください。現在はそこで実行できます。 - 価格やプランに関する質問には通常通り回答します。
以下のキー、アカウントツール、画像やクリップの制作に関するセクションは、tools/listにそれらのツールが表示された場合に適用されます。
ルール
- 価格を記憶から引用しないでください。 価格は変動します。
estimate_website_clips_cost（キーあり）、get_video_prices、またはget_plans_and_pricingを毎回呼び出し、返されたものと、返された価格ページのリンクを引用してください。 - ユーザーが正確な価格に同意した場合のみ課金してください。
create_image、create_video_clip、edit_imageのみが課金し、これらはアカウントのAPI残高（Gemとは別）から米ドルで支払われます。estimate_image_cost、estimate_video_clip_cost、またはestimate_image_edit_costで見積もりを取得し、何を作成するか、その費用（price）をユーザーに伝え、明確な同意を待ってください。その場合にのみconfirmed_by_userをtrueに設定し、決して自分で設定しないでください。見積もられた引数をそのまま送信してください。価格が変わったか見積もりが期限切れになった場合は、再度見積もりを取得し、再度確認を取ってください。同じジョブを2回開始しないでください：start_unknownの後は、まずlist_my_gems_chargesとlist_my_video_projectsを確認してください。クリップは、ユーザーがZoromi上で所有する画像（first_frame、そのIDまたはZoromi上のアドレス）から開始できますが、ユーザーが「この画像に写っている全員が使用に同意しました」（people_consent）と「この画像を使用する権利があります」（rights_confirmed）に同意した場合に限ります。必ず確認し、決して仮定しないでください。本、ユーザー自身の画像から作成された画像、およびドラマ全体は、現在のところウェブサイト上で作成されます：get_zoromi_overviewからのリンクをユーザーに提供してください。ツールがcontent_not_allowedと応答した場合、コンテンツポリシーがリクエストを許可しません：その旨をユーザーに伝え、ポリシーを回避するために言い換えを行わないでください。 - APIキーを秘密に保ってください。
ZOROMI_API_KEY環境変数から読み取ってください。決して印刷、エコー、プロジェクト内のファイルへの書き込み、コミットへの追加、チャットへの貼り付けを行わないでください。送信先はzoromi.studioのみです。 - HTTPステータスではなく、応答の内容を確認してください。 ツールはHTTP 200を応答しても問題を報告することがあります：
result.structuredContentの前にresult.isErrorを確認してください。エラーを参照してください。 - ツールが返すリンクを使用してください（価格ページ、アカウントページ、本の
open_urlなど）。URLをでっち上げないでください。 - ユーザーには平易な言葉で伝えてください。 Gemはウェブサイト上のZoromiのクレジットであり、API残高は米ドルです。「10セグメント中3セグメントが撮影済み」のような回答は、生のフィールド名よりも優れています。
セットアップ
APIキー
アカウントツールが開放されていない間は、このセクションをスキップしてください（開放されているものを参照）。
価格、プラン、get_zoromi_overviewにはキーは必要ありません。アカウントに関するすべてには、そのアカウント所有者のキー（zk_live_で始まります）が必要です。所有者はZoromiのアカウントページで作成します（get_zoromi_overviewがリンクを返します）。ユーザーがまだキーを持っていない場合は、キーなしで可能な範囲で回答し、どこで作成すればよいかを伝えてください。
ユーザーはプロジェクトの外部で一度だけ設定します：
# macOS / Linux：~/.zshrc または ~/.bashrc に追加
export ZOROMI_API_KEY='zk_live_...'
# Windows PowerShell（現在のユーザー、永続的）
[Environment]::SetEnvironmentVariable('ZOROMI_API_KEY', 'zk_live_...', 'User')
コマンドでZOROMI_API_KEYが空であると表示された場合は、ユーザーに設定するように依頼してください。キーをチャットに貼り付けるように依頼しないでください。
オプションA: MCPサーバーとして接続（Claude Codeおよびその他のMCPクライアント）
APIは、https://zoromi.studio/api/v1/mcp/skill でStreamable HTTP上のMCPサーバーです。Claude Codeでは、プロジェクトの.mcp.jsonにこれを配置します。キーは環境変数に残ります：Claude Codeは接続時に${ZOROMI_API_KEY}を展開するため、ファイルには秘密情報は保持されません。
{
"mcpServers": {
"zoromi": {
"type": "http",
"url": "https://zoromi.studio/api/v1/mcp/skill",
"headers": { "Authorization": "Bearer ${ZOROMI_API_KEY}" }
}
}
}
ツールは名前で表示され（get_video_pricesなど）、直接呼び出すことができます。
オプションB: curlで呼び出す（任意のエージェント）
各呼び出しは、JSON-RPC tools/callメッセージの1回のHTTP POSTです。セッションや事前のハンドシェイクはありません。以下のシェル関数により、各呼び出しを1行で行えます。標準入力（-H @-）を介してキーを送信するため、キーがコマンドラインやプロセスリストに表示されることはありません。
# 使用法: zoromi <ツール名> ['<json引数>']
zoromi() {
tool=${1:?使用法: zoromi <ツール名> [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}'
- 必要なのは
curlのみです。jqは応答の読み取りに便利ですが（... | jq .result.structuredContent）、必須ではありません。 - Windows：Git BashまたはWSLで実行してください。PowerShellでは、
curlは別のコマンドです。curl.exeを使用し、ボディをファイルに書き込んで（--data-binary "@body.json"）引用の問題を回避してください。 - すべてのツールとその引数スキーマを一覧表示するには：同様に
{"jsonrpc":"2.0","id":1,"method":"tools/list"}を送信してください。
ツール
| ツール | キー | 引数 | 応答内容 |
|---|---|---|---|
get_zoromi_overview | 不要 | なし | Zoromiが作成するもの、開始方法、リンク（ウェブサイト、サインアップ、価格、アカウント） |
get_video_prices | 不要 | なし | モデルと解像度ごとの、効果音付き5秒クリップあたりの現在のGem数、および現在の割引 |
get_plans_and_pricing | 不要 | なし | 現在のプラン（月額／年額、付与Gem数）、都度払い、Gemパック |
get_my_account | 必要 | なし | プラン、Gem残高、今日のデイリー上限、今日の使用済みと残り |
list_my_books | 必要 | limit 1-100、offset、query | ユーザーのイラストブック（新しい順） |
get_book | 必要 | book_id | 1冊の本：ステータスと各ページのステータス、画像、冒頭テキスト |
list_my_video_projects | 必要 | limit 1-100、offset | ユーザーのビデオプロジェクト（新しい順）、セグメントの状態別カウント付き |
get_video_project | 必要 | project_id | 1つのビデオプロジェクトとそのセグメントの状態別カウント |
get_generation_status | 必要 | task_id | 1つの生成ジョブ：キュー中、実行中、完了、または失敗。完了時はview_url（ユーザーが表示・ダウンロードするための自身のページ）と、ここで作成された画像の請求額 |
list_my_gems_charges | 必要 | limit 1-200 | 最近のGemのチャージと返金（新しい順） |
estimate_website_clips_cost | 必要 | model、resolution、seconds_per_clip、clips、aspect_ratio、with_sound | このアカウントの価格でその数のクリップを撮影するのに必要なGem数、および残高で賄えるかどうか。課金なし |
estimate_image_cost | 支出用キー | prompt、およびオプションでmodel、aspect_ratio、quality | この1枚の画像の正確な価格とquote_id（短命、1回限り使用）。課金なし |
create_image | 支出用キー | 同上に加え、quote_idとconfirmed_by_user | 見積もられた画像を作成し、その価格をAPI残高に請求します。task_idを応答 |
estimate_image_edit_cost | 支出用キー | pictures（ユーザーのZoromi上の画像1〜4枚）、prompt、people_consent、rights_confirmed、およびオプションでmodel、aspect_ratio、quality | この編集の正確な価格とquote_id（短命、1回限り使用）。課金なし |
edit_image | 支出用キー | 同上に加え、quote_idとconfirmed_by_user | 見積もられた編集を適用し、その価格をAPI残高に請求します。task_idを応答 |
estimate_video_clip_cost | 支出用キー | model、resolution、seconds、prompt、aspect_ratio、with_sound、および開始画像がある場合はfirst_frame、people_consent、rights_confirmed | この1つのクリップの正確な価格とquote_id（短命、1回限り使用）。課金なし |
create_video_clip | 支出用キー | 同上に加え、quote_idとconfirmed_by_user | 見積もられたクリップを作成し、その価格をAPI残高に請求します。task_idを応答 |
estimate_website_story_video_cost | 必要 | model、resolution、clips、seconds_per_clip、cards、aspect_ratio | 1エピソードの見積もり：撮影と画像。課金なし |
start_website_story_video | 支出用キー | script、およびオプションでtitle、model、resolution、aspect_ratio、seconds_per_clip、target_minutes、keep_my_writing、dialogue_language | スクリプトからウェブサイト上にプロジェクトを作成し、open_urlとユーザーがそこで押すボタンを応答。課金なし |
get_website_story_video_status | 必要 | project_id | ドラマの進行段階、撮影済みクリップ、準備完了時の動画リンク、次に押すべきボタン |
「支出用キー」とは、アカウントページでアカウント所有者が画像とクリップの作成を許可し、1日あたりのドル制限を設定したキーです。作成されたものはアカウントのAPI残高（アカウントページで所有者がチャージします。Gemとは別であり、相互に支払いに使用されることはありません）から支払われます。estimate_image_cost、create_image、estimate_image_edit_cost、edit_image、estimate_video_clip_cost、create_video_clipは、他のキーではリストされません。
キーがある場合、get_video_pricesはそのアカウント固有の価格（プランによって変更可能）を応答します。キーがない場合は公開価格を応答します。
よくあるリクエスト
「Nクリップの短編ドラマの費用はいくらですか？」 キーがある場合、モデルと解像度（get_video_pricesがリストする通りの名前）、クリップあたりの秒数、クリップ数を指定してestimate_website_clips_costを呼び出します。縦型ドラマはaspect_ratio 9:16（デフォルト）です。gems_total、gems_per_clip、enough_gemsを報告し、coversが示す内容を伝えてください。クリップの撮影が主な費用ですが、キャラクターの画像、計画、音声、音楽も課金され、ウェブサイトでは支出前に正確な合計が表示されます。モデルが長さを丸める場合、応答にはseconds_noteが含まれます。それを伝えてください。キーがない場合、get_video_pricesを呼び出し、そのモデルと解像度のgems_per_secondに総秒数を掛けて撮影費用を推定し、計算過程を示してください。
「どのプランを選べばいいですか？」 get_plans_and_pricingを呼び出し、各プランが付与するGem数と上記の見積もりを比較し、返された価格ページにリンクしてください。
「Gemはいくつありますか？」 get_my_account。また、デイリー上限と、アカウントに上限がある場合は本日の残りについても言及してください。
「動画はできましたか？」 list_my_video_projects、次にプロジェクトのidを指定してget_video_projectを呼び出します。状態別にカウントされたセグメントを報告してください。ユーザーがすでに持っている1つのジョブIDについては、get_generation_statusを使用してください。
「私の本はどこですか？」 list_my_books（queryでタイトル検索可能）、次にget_bookを呼び出します。本のopen_urlを提供してください。
「いくら使いましたか？」 list_my_gems_charges。チャージと返金はGem単位です。ユーザーが尋ねた期間について合計し、返された使用量ページにリンクしてください。
「...の画像を作ってください」 支出用キーがある場合：
estimate_image_costを、プロンプト（誰が、何を、どこで、光、スタイル）と、ユーザーがフレーム形状を指定した場合はaspect_ratioを指定して呼び出します。ユーザーが指定しない限り、modelとqualityは省略します。- 作成されるものとその
priceをユーザーに伝え、確認を求めます。enough_balanceがfalseの場合は、API残高で賄えないことを伝え、チャージのためのaccount_pageを提供します。 - 明確な同意の後、同じ引数、
quote_id、confirmed_by_user: trueを指定してcreate_imageを呼び出します。 get_generation_statusをtask_idを指定して5秒以上間隔でSUCCESSまたはFAILUREになるまで確認し、ユーザーにview_url（Zoromi上のユーザー自身のページ、画像のresult_urlも存在する場合はそれも）と、chargeが示す請求額を提供します。画像が最終的に失敗した場合、請求された額はAPI残高に戻ります。
「この画像を変更してください...」 支出用キーがある場合：
- 画像は、ユーザー自身がZoromi上で所有するもの（そのID、またはZoromiが付与したアドレス）である必要があります。
create_imageで作成された画像は機能します：完了時にget_generation_statusが応答したアドレスを渡してください。他のウェブアドレスは受け付けられません。自分でアップロードや取得を行わないでください。 - ユーザーに「この画像に写っている全員が使用に同意しました」と「この画像を使用する権利があります」の両方を尋ね、それぞれに明確な同意があった場合のみ
trueを送信してください。 - 最初の見積もりと同じパターンで進めてください。新しい画像は編集用の画像として扱われます。
「このキャラクターの短編ドラマを作ってください」 キーがある場合：
- ドラマ全体はウェブサイト上で仕上げられます。ユーザーに
start_website_story_videoからのリンクを渡し、そこで何ができるかを伝えてください。スクリプト（最低でも50語）があれば、start_website_story_videoを呼び出します。タイトルはオプションです。各クリップは模型のデフォルト秒数になります。target_minutesを設定してクリップ数を変えることもできます。keep_my_writingをtrueに設定すると、スクリプトの言葉が保持されます。合計時間はget_video_pricesの模型の「1クリップあたりの秒数」を確認して見積もってください。 open_urlをユーザーに与え、そこに表示されるボタンを押すよう伝えてドラマを仕上げます。get_website_story_video_statusで、ビデオプロジェクトのproject_idを使用して進行状況を追跡できます。"
エラー
APIの応答は、エラーが発生してもHTTP 200を返す場合があります。result.isErrorがtrueの場合、result.structuredContentにはエラーが含まれます。
{
"result": {
"isError": true,
"structuredContent": [
{ "type": "text", "text": "認証に失敗しました。APIキーを確認してください。" }
]
}
}
発生する可能性のあるエラー：
- 認証エラー：キーが無効または期限切れです。アカウントページで新しいキーを作成するようユーザーに伝えてください。
- 残高不足：API残高が十分ではありません。アカウントページでチャージするようユーザーに伝えてください。
- コンテンツが許可されていません：リクエストがコンテンツポリシーに違反しています。内容を言い換えずに、その旨をユーザーに伝えてください。
- 割り当て超過：レート制限を超えました。少し待ってから再試行してください。
制限事項
- 画像編集：1回の呼び出しで最大4枚の画像。編集できるのはユーザー自身のZoromi上の画像のみです。
- 短編ドラマ：ドラマ全体の作成はウェブサイト上で行われます。このスキルは、スクリプトからプロジェクトを開始し、ステータスを確認することのみが可能です。
- 本：イラストブックの作成はウェブサイト上で行われます。このスキルは、本のリストと詳細の表示のみが可能です。
- 支出キー：画像とクリップの作成には、「支出用」としてマークされた特別なAPIキーが必要です。通常の読み取り専用キーではこれらの操作を実行できません。
トラブルシューティング
ZOROMI_API_KEYが設定されていない
環境変数が正しく設定され、シェルが再起動されていることを確認してください。
tools/listに予想したツールが表示されない
キーが正しいこと、およびアカウントに必要な権限があることを確認してください。段階的な開放により、一部のツールは最初は利用できません。
画像作成が「コンテンツが許可されていません」で失敗する プロンプトがZoromiのコンテンツポリシーに違反している可能性があります。言い換えずに、その旨をユーザーに伝えてください。
見積もりが期限切れになる 見積もりは短命です。新しい見積もりを取得し、再度確認を取ってください。
ジョブがハングしているように見える
get_generation_statusでステータスを確認してください。キューイングや処理に時間がかかる場合があります。