Zoromi for AI agents (中文版)

Zoromi (https://zoromi.studio) 將故事或點子轉化為插圖書或短影片（包含腳本、分鏡、配音、音樂和剪輯），並營運短劇院。此技能讓您能回答價格、方案以及使用者帳戶的相關問題，並為使用者製作一張圖片或一部影片剪輯，方法是呼叫 Zoromi API。

每個工具的逐欄解答：references/tools.md

什麼是開放的

伺服器會分階段開放其工具。在提供任何服務之前，請先呼叫 tools/list，並僅使用它所列出的工具。

始終開放，無需金鑰： get_zoromi_overview、get_video_prices 和 get_plans_and_pricing。
當 tools/list 顯示它們時： 讀取帳戶（餘額、書籍、專案、任務、收費）的工具，以及製作東西的工具。尚未開放的工具會回應「此工具尚未開放。」

當 tools/list 僅顯示上述三個開放工具時：

請勿向使用者索取 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 餘額中支付，該餘額與寶石分開計算。使用 estimate_image_cost、estimate_video_clip_cost 或 estimate_image_edit_cost 取得報價，告知使用者它會製作的內容及其成本 (price)，然後等待明確的同意。只有在使用者確認後，才能將 confirmed_by_user 設為 true，絕不能自行設定。請準確傳送已報價的參數。如果價格變動或報價過期，請重新報價並再次詢問。絕不要重複啟動相同的任務：在 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。
用淺顯的文字與使用者溝通。 寶石是 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 是一個透過 Streamable HTTP 運作的 MCP 伺服器，位址為 https://zoromi.studio/api/v1/mcp/skill。在 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 訊息的 HTTP POST。沒有 session，也不需要先進行交握。這個 shell 函數讓每次呼叫變成一行的指令。它透過標準輸入 (-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 並將 body 寫入檔案（--data-binary "@body.json"）以避免引號問題。
若要列出每個工具及其參數結構：以相同方式傳送 {"jsonrpc":"2.0","id":1,"method":"tools/list"}。

工具

工具	金鑰	參數	回傳內容
`get_zoromi_overview`	無	無	Zoromi 提供什麼、如何開始、連結（網站、註冊、定價、帳戶）
`get_video_prices`	無	無	每個 5 秒含音效剪輯的即時寶石數，依模型和解析度區分，以及任何當前的折扣
`get_plans_and_pricing`	無	無	即時方案（月費/年費、贈送寶石數）、隨用隨付方案、寶石包
`get_my_account`	有	無	方案、寶石餘額、今日每日上限、今日已使用及剩餘寶石
`list_my_books`	有	`limit` 1-100, `offset`, `query`	使用者的插圖書，最新者優先
`get_book`	有	`book_id`	一本書：狀態及各頁的狀態、圖片和開場文字
`list_my_video_projects`	有	`limit` 1-100, `offset`	使用者的影片專案，最新者優先，並附上依狀態計數的片段
`get_video_project`	有	`project_id`	一個影片專案及其依狀態計數的片段
`get_generation_status`	有	`task_id`	一個生成任務：佇列中、執行中、完成或失敗；完成時，提供 `view_url`（使用者查看和下載的頁面）以及在此處製作的圖片被收取的費用
`list_my_gems_charges`	有	`limit` 1-200	最近的寶石收費和退款，最新者優先
`estimate_website_clips_cost`	有	`model`, `resolution`, `seconds_per_clip`, `clips`, `aspect_ratio`, `with_sound`	以此帳戶的價格拍攝這些片段所需的寶石數，以及餘額是否足夠。不會產生任何費用
`estimate_image_cost`	消費金鑰	`prompt`, 以及選填的 `model`, `aspect_ratio`, `quality`	這張圖片的確切價格和一個 `quote_id`（短暫有效，僅用一次）。不會產生任何費用
`create_image`	消費金鑰	同上，再加上 `quote_id` 和 `confirmed_by_user`	製作已報價的圖片並從 API 餘額中扣除其費用；回傳一個 `task_id`
`estimate_image_edit_cost`	消費金鑰	`pictures` (1-4 張使用者在 Zoromi 上的圖片), `prompt`, `people_consent`, `rights_confirmed`, 以及選填的 `model`, `aspect_ratio`, `quality`	此次編輯的確切價格和一個 `quote_id`（短暫有效，僅用一次）。不會產生任何費用
`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`	這個剪輯的確切價格和一個 `quote_id`（短暫有效，僅用一次）。不會產生任何費用
`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`	一集的估算：拍攝加上圖片。不會產生任何費用
`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`	劇集進行到哪個步驟、已拍攝的片段數、完成時的影片連結、下一步該按什麼

「消費金鑰」是帳戶擁有者在帳戶頁面上允許用來製作圖片和剪輯的金鑰，並設定了他們指定的每日美元上限。其製作的內容從帳戶的 API 餘額支付，該餘額由擁有者在帳戶頁面充值；它與寶石分開計算，兩者不能互相支付。estimate_image_cost、create_image、estimate_image_edit_cost、edit_image、estimate_video_clip_cost 和 create_video_clip 不會為其他金鑰列出。

使用金鑰時，get_video_prices 會以該帳戶自己的價格回應，方案可能會改變這個價格。沒有金鑰時，它會以公開價格回應。

常見請求

「一部 N 個剪輯的短劇要多少錢？」 使用金鑰，呼叫 estimate_website_clips_cost，參數為模型和解析度（名稱必須與 get_video_prices 列出的完全相同）、每個剪輯的秒數和剪輯數量；垂直劇集的 aspect_ratio 為 9:16，這是預設值。回報 gems_total、gems_per_clip 和 enough_gems，並說明 covers 的內容：拍攝剪輯是主要成本，但角色圖片、規劃、配音和音樂也會被收費，網站在實際消費前會顯示確切總額。如果模型會四捨五入長度，回應中會有 seconds_note；請傳達這個資訊。沒有金鑰時，呼叫 get_video_prices 並估算拍攝成本為該模型和解析度的總秒數乘以 gems_per_second，並顯示計算過程。

「我應該選擇哪個方案？」 呼叫 get_plans_and_pricing，比較每個方案提供的寶石數與上述估算，並提供它回傳的定價頁面連結。

「我有多少寶石？」 get_my_account。當帳戶有每日上限時，也提一下今天的上限和剩餘量。

「我的影片完成了嗎？」 list_my_video_projects，然後用專案的 id 呼叫 get_video_project。回報依狀態計數的片段。對於使用者已有的單一任務 ID，使用 get_generation_status。

「我的書在哪裡？」 list_my_books（使用 query 按標題搜尋），然後 get_book。提供書籍的 open_url。

「我花了多少錢？」 list_my_gems_charges。收費和退款以寶石為單位；將使用者詢問期間的費用加總，並提供它回傳的使用量頁面連結。

「幫我做一張……的圖片」 使用消費金鑰：

使用提示詞（誰或什麼、在哪裡、光線、風格）以及如果使用者要求了外框形狀則加上 aspect_ratio，來呼叫 estimate_image_cost。除非使用者要求，否則省略 model 和 quality。
告知使用者將要製作的內容及其 price，並詢問。如果 enough_balance 為 false，則說明 API 餘額不足，並提供 account_page 讓他們充值。
在獲得明確同意後，使用相同的參數、quote_id 和 confirmed_by_user: true 來呼叫 create_image。
每 5 秒或更長時間檢查一次 get_generation_status，直到 SUCCESS 或 FAILURE，然後提供使用者 view_url（他們在 Zoromi 上查看和下載的頁面；如果有的話也提供圖片的 result_url）以及 charge 所說明的費用。當圖片最終失敗時，已收取的費用會退回到 API 餘額。

「修改這張圖片……」 使用消費金鑰：

圖片必須是使用者在 Zoromi 上的圖片：其 ID，或 Zoromi 為其提供的位址。使用 create_image 製作的圖片有效：傳遞 get_generation_status 在圖片完成時所回應的位址。不接受其他網站位址；不要自行上傳或抓取任何內容。
按照順序詢問使用者這兩個問題，並且僅在每個都獲得明確同意後才傳送 true：「此圖片中的所有人都同意被使用」以及「我有權使用此圖片」。
使用使用者圖片 ID、提示詞、people_consent、rights_confirmed 以及選填的 model、aspect_ratio、quality 來呼叫 estimate_image_edit_cost。
告知使用者修改的內容及其 price，並詢問。如果 enough_balance 為 false，則說明 API 餘額不足，並提供 account_page 讓他們充值。
在獲得明確同意後，使用相同的參數、quote_id 和 confirmed_by_user: true 來呼叫 edit_image。
輪詢 get_generation_status 直到完成，然後提供 view_url 和費用。

「為我啟動一個短劇……」 使用消費金鑰：

使用腳本以及選填的標題、模型、解析度、外框比例（預設為 9:16）、每個剪輯的秒數、目標分鐘數、keep_my_writing 和 dialogue_language 來呼叫 start_website_story_video。
回傳 open_url（使用者在那裡完成短劇的頁面）以及 buttons 陣列，該陣列說明使用者接下來需要按下什麼按鈕：將其傳達給使用者。它還會回傳 project_id、title 和 status。
如果使用者稍後詢問進度，使用 project_id 呼叫 get_website_story_video_status。

錯誤

result.isError 為 true 時，result.content 是一個包含單一元素的陣列： {"type":"text","text":"{\"error\":\"...\",\"message\":\"...\"}"}。解析它。常見的 error 值：
- content_not_allowed：內容政策不允許請求。告訴使用者原因；不要為了繞過政策而改寫請求。
- invalid_key 或 key_not_found：金鑰無效。建議使用者檢查環境變數，如果是 zk_live_... 以外的字符串，請他們在帳戶頁面上檢查金鑰。
- insufficient_balance：API 餘額（美元）不足以支付 create_image、create_video_clip 或 edit_image 的費用。回傳的 message 包含帳戶頁面的 account_page 連結，提供給使用者。
- quota_exceeded：消費金鑰已達到其每日上限。說明日數。
HTTP 錯誤：用戶端錯誤（4xx）或伺服器錯誤（5xx）。對於 404，伺服器可能處於維護中，或者工具名稱有誤——再次檢查 tools/list。
工具未開放：JSON-RPC 回應包含 isError: true，其中 error 為 tool_not_open。解決方案：告訴使用者「此功能尚未從助手端開放。前往 zoromi.studio 的網站即可使用。」
quote_id 過期：create_image、create_video_clip 或 edit_image 回應 isError: true，其中 error 為 quote_expired。重新報價然後再試一次。

實作提示

分階段開放工具： 始終從 tools/list 開始。如果顯示的三個開放工具是 get_zoromi_overview、get_video_prices 和 get_plans_and_pricing，則不要要求金鑰。
引數驗證： aspect_ratio 接受由冒號分隔的兩個整數：16:9、9:16、1:1、4:5、9:18、9:21。
挑選模型： 如果使用者沒有指定解析度，請使用 Zoromi 預設值。使用 get_video_prices 回傳的 model_name 和 resolution 名稱作為 estimate_* 和 create_* 的引數。
短劇估算 (estimate_website_clips_cost)： 這是拍攝成本。這是一個近似值。回報 gems_total、gems_per_clip、enough_gems 和 covers。
輪詢生成狀態： 對於 create_image、edit_image 和 create_video_clip，每 5 秒輪詢一次 get_generation_status。對於較長的任務可以更長。不要在同一個任務 ID 上同時執行兩個輪詢。
在獲得同意之前，不要執行 create_image、edit_image、create_video_clip。 總是先報價，獲得明確的同意，然後才帶上 confirmed_by_user: true。
使用者自己的圖片： 如果使用者想要從他們的 Zoromi 帳戶中的圖片開始製作影片剪輯，該圖片必須是他們自己的圖片，在 Zoromi 上。first_frame 接受：Zoromi 站上的圖片位址、圖片 ID，或 result_url。如果使用者要求的是您無法控制的網頁或上傳的圖片，請說明這必須是他們 Zoromi 帳戶中的圖片。

Zoromi Studio 技能