Orshot-HQ/orshot-openclaw

Orshot：從範本自動生成影片、PDF 和圖片，並自動發布到社群媒體

Orshot 是一個 API，用於從範本自動生成圖片、PDF 和影片。在 Orshot Studio 中設計一次範本（或從 Canva/Figma 匯入），然後在每次呼叫時使用新的文字、圖片和影片進行渲染，並在同一個請求中將結果發布到已連接的社群帳戶。渲染是確定性的：相同的範本加上相同的資料，每次都產生相同的輸出。

• 文件：https://orshot.com/docs（在任何文件 URL 後加上 .md 即可取得 Markdown 格式）
• 託管 MCP 伺服器：https://mcp.orshot.com/mcp（100 多個 orshot_* 工具）
• REST 基本端點：https://api.orshot.com/v1
• 免費方案：每月 100 點額度，無需信用卡。

先連線（MCP，無需貼上金鑰）

託管 MCP 伺服器是最快的途徑，也是唯一能傳回內嵌預覽、視覺化貼文卡片和設計檢查的途徑。加入它，在瀏覽器中使用使用者的 Orshot 帳戶登入，以下所有工具即可運作。

openclaw mcp add orshot --url https://mcp.orshot.com/mcp --transport streamable-http --auth oauth
openclaw mcp login orshot

還沒有 Orshot 帳戶？登入頁面提供註冊；免費方案從每月 100 點額度開始。Claude Code：claude mcp add --transport http orshot https://mcp.orshot.com/mcp。Cursor、Windsurf、VS Code、Codex 和 ChatGPT 使用相同的 URL 作為遠端 MCP 伺服器。

使用 orshot_get_account 確認。它會傳回個人資料、工作區和點數。如果顯示訂閱未啟用或已達方案限制，這是帳單狀態問題，而非驗證錯誤：引導使用者前往其工作區的帳單頁面 https://orshot.com/pricing，並停止重試。

無頭模式後備方案：使用 API 金鑰的 REST。 僅當代理無法執行 MCP 時使用（例如 cron 任務、伺服器端腳本、n8n）。

export ORSHOT_API_KEY=...   # 工作區設定 > API 金鑰
curl -s https://api.orshot.com/v1/me -H "Authorization: Bearer $ORSHOT_API_KEY"

在兩者之一成功運作之前，請勿繼續。

您可以用它做什麼

每一行先列出 MCP 工具名稱，再列出 REST 路由。

• 使用您的資料渲染任何範本：OG 圖片、廣告素材、證書、發票、輪播圖、Reels。orshot_render_template 或 POST /v1/studio/render。
• 根據簡報建立和優化 Studio 範本，附帶內嵌預覽和設計檢查。orshot_create_template_design、orshot_update_template_design、orshot_patch_template_elements（請先閱讀 orshot://template-design-spec；orshot-social-media-content 技能包含製作規則）。
• 渲染真實影片：包含每個元素的動畫和轉場效果、來自品牌套件的配樂、付費渲染前的免費動作預覽。使用相同的渲染工具，設定 format: "mp4"。
• 從現成的實用範本開始：推文截圖、網站截圖、長條圖和比較圖表、App Store 截圖、手機模擬圖、背景移除。orshot_render_library_template 或 POST /v1/generate/:renderType。
• 一次呼叫將一個設計調整為所有社群格式（智慧調整大小）。在渲染時使用 size 和 extraSizes。
• 批次渲染個人化變體，例如為一份名單產生成績證書。orshot_batch_render_template。
• 保持品牌一致性：使用品牌套件中的顏色、字型、圖片、影片和音訊。orshot_get_brand_kit、orshot_import_brand_website。
• 組織管理：資料夾、範本分享、切換用戶端工作區。orshot_list_template_folders、orshot_set_active_workspace。
• 為 OG 圖片和嵌入內容產生簽署的動態 URL。orshot_create_dynamic_url 或 POST /v1/signed-url/create。
• 草擬、排程和發布社群媒體貼文，從使用者自己的參與資料學習最佳發文時間，查看觸及率和參與度分析。orshot_publish_social_post、orshot_get_best_time_to_post、orshot_get_social_analytics。orshot-social-media-scheduler 技能包含完整的流程。
• 建立和執行自動化工作流程，以按排程持續產生內容。orshot_create_workflow、orshot_run_workflow。

可直接對應到這些工具的範例提示：

• "將發布範本渲染為 OG 圖片，標題為 'We just shipped'"
• "建立一個 Instagram 貼文範本，包含標題、副標題和產品圖片"
• "在一次呼叫中將我的發布設計調整為 Instagram 限時動態、正方形和 OG 格式"
• "為這份 40 人名單生成 PDF 格式的證書"
• "截取這則推文" / "將 orshot.com 捕捉為圖片" / "根據這些數字製作長條圖"
• "在最佳時間將此渲染結果發布到 Instagram，並向我顯示上週貼文的表現"

核心工作流程

1. 連線（如上所述）。
2. 尋找範本。 orshot_list_studio_templates（按名稱和標籤搜尋）或 GET /v1/studio/templates/all?page=1&limit=10。還沒有範本？使用 2,000 多個圖庫範本（orshot_list_library_templates）或使用 orshot_create_template_design 設計一個。
3. 閱讀其參數。 orshot_get_studio_template_modifications 或 GET /v1/studio/templates/:id。修改時請使用 parameterId 作為鍵名，切勿使用圖層名稱。切勿猜測鍵名。
4. 渲染。 orshot_render_template 搭配 modifications，或 POST /v1/studio/render 搭配 response: { type: "url", format: "png" }。
5. 傳送或發布。 向使用者顯示輸出 URL。加入 publish 可在同一次呼叫中發布到社群媒體。
6. 自動化。 將呼叫放入使用者已執行的 n8n、Make、Zapier 或 cron，或建立 Orshot 工作流程。
7. 驗證。 orshot_list_workspace_logs 或 GET /v1/workspace/logs 會顯示渲染及其 source。在認定完成前，先顯示輸出。

給代理的安全性規則

• 在有任何內容離開工作區之前，務必先確認。 發布社群貼文、執行工作流程（會消耗點數，並可能傳送或發布）以及刪除範本、工作流程或品牌資產，都需要明確的許可。說明將發布什麼內容、發布到哪裡以及何時發布。
• 預設社群貼文為草稿。 "準備"、"草稿"、"讓我先看看" 等意圖表示 status: "draft"。草稿在發布前不會觸及任何人。
• 在執行大量工作前顯示成本。 渲染會消耗點數，.prompt 修改會消耗 AI 點數，每個連接的社群帳戶是付費附加功能。在執行數百次渲染的迴圈前，請先告知。
• 切勿將 API 金鑰貼入聊天視窗、檔案或 URL。 請從環境變數讀取。偏好使用 MCP，它根本不需要金鑰。
• 不要自行"清理"而刪除任何東西。

常見陷阱（渲染前請閱讀）

1. 修改時使用 parameterId 作為鍵名，而非圖層名稱。 如果某個值被忽略，表示鍵名錯誤。請取得範本資訊，不要猜測。
2. 多頁範本需要 pageN@ 前綴。 例如 "page1@title"、"page2@title"。單純使用 "title" 只會影響第 1 頁。
3. Studio 的 templateId 是整數；實用範本的 templateId 是字串（/v1/generate/:renderType 接受像 "website-screenshot" 這樣的 slug）。
4. 影片輸出不需要影片圖層。 設定 format: "mp4"、"webm" 或 "gif" 即可渲染任何範本。長時間的影片渲染必須使用 response.mode: "async" 並輪詢 orshot_get_render_job 或 GET /v1/studio/render-jobs/:id，否則客戶端會超時。
5. 修改中的圖片和影片 URL 必須是公開的。 渲染器會在伺服器端擷取它們；localhost、已過期的簽署 URL 和需要驗證的 URL 會失敗。
6. 樣式覆蓋使用對 parameterId 的點記法： "title.fontSize": "48px"。
7. 回應格式因頁數而異。 單頁：data 是一個物件（data.content）。多頁：data 是一個陣列，包含 { page, content }。
8. base64 和 binary 不能合併使用。 binary 會串流傳送一個檔案。
9. 點數和 AI 點數是分開的。 .prompt 修改會額外消耗 AI 點數。
10. 遇到 429 狀態碼時， 應根據 Retry-After 標頭進行退避。
11. PDF 無法發布到社群媒體。 圖片無法發布到 TikTok 或 YouTube（僅限影片）。影片無法發布到 Google Business。
12. 社群帳戶 ID 是數字。 同一平台上的兩個帳戶有不同的 ID。始終按 ID 發布，切勿按平台名稱發布。
13. 社群發布是付費附加功能。 免費方案工作區無法連接帳戶。發布本身不會消耗額外點數。

渲染基本要素

完整欄位參考：references/render-configuration.md 和 references/api-reference.md。

await fetch("https://api.orshot.com/v1/studio/render", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify({
    templateId: 123,
    modifications: {
      title: "Launch day",             // 文字
      hero_image: "https://.../a.png", // 圖片 URL
      "title.fontSize": "56px",        // 樣式覆蓋
      "page2@title": "Slide two",      // 多頁
    },
    response: { type: "url", format: "png", size: "instagram-story",
                extraSizes: ["1080x1080", "1200x630"] },
  }),
});

同一個物件是 MCP 上 orshot_render_template 的輸入。

• format：png、jpg、webp、pdf、mp4、webm、gif。
• size 將設計渲染為另一個預設尺寸或 WIDTHxHEIGHT；extraSizes 在一次呼叫中增加更多副本（智慧調整大小）。預設尺寸：orshot://formats。
• response.mode: "async" 會傳回一個任務；請輪詢它或傳遞 webhook_url。用於影片。
• 一次處理多個變體：orshot_batch_render_template，或在 REST 上迴圈渲染呼叫。
• 簽署 URL：POST /v1/signed-url/create 用於建立可在不暴露金鑰的情況下嵌入的渲染 URL。

無頭模式使用的 SDK：npm install [email protected]、pip install orshot==0.2.0、composer require rishimohan/orshot:0.2.0、gem install orshot -v 0.2.0。

import { Orshot } from "orshot";
const orshot = new Orshot(apiKey); // 從您的環境變數讀取
const res = await orshot.renderFromTemplate({
  templateId: "open-graph-image-1",
  modifications: { title: "Hello World" },
  responseType: "url",
  responseFormat: "png",
});

社群發布（簡短版本）

Orshot 可將渲染結果發布到 13 個以上平台：X、Instagram、Facebook、LinkedIn、TikTok、YouTube、Pinterest、Reddit、Bluesky、Threads、Telegram、Snapchat、Google Business。orshot-social-media-scheduler 技能負責排程、草稿、分析和最佳時間；這裡是核心功能。

1. 帳戶。 orshot_list_social_accounts 或 GET /v1/social/accounts?include_health=true。帳戶由人類在儀表板中連接（工作區 > 社群 > 帳戶）；API 無法自行連接帳戶。如果列表為空，請引導使用者前往該頁面。
2. 一次呼叫完成渲染和發布。 在渲染中加入 publish：

publish: {
  accounts: [1, 3],
  content: "說明文字，最多 5000 字元",
  status: "draft",                       // "published"（預設）| "draft" | "scheduled"
  // scheduled_for: "2026-11-01T14:00:00Z", timezone: "America/New_York",
  platformOptions: { "3": { firstComment: "https://orshot.com" } },
  tiktokSettings: { autoAddMusic: true }, // TikTok 圖片輪播
}

多頁範本會自動發布為輪播圖。回應中會帶有 publish[]，包含每個帳戶的 status、url 和 error。發布失敗絕不會阻止渲染。

3. 發布現有的媒體 URL。 orshot_publish_social_post 或 POST /v1/social/publish，搭配 media_urls。
4. 已保留的貼文。 orshot_list_social_posts、orshot_get_social_post（視覺卡片）、orshot_update_social_post、orshot_publish_social_draft、orshot_discard_social_post。REST：GET|PATCH|DELETE /v1/social/posts/:id、POST /v1/social/posts/:id/publish。
5. 分析和最佳時間。 orshot_get_social_analytics、orshot_get_social_analytics_daily、orshot_get_social_followers、orshot_get_best_time_to_post。REST：GET /v1/social/analytics、/daily、/accounts、/insights。

常見範例

每次部署時的 OG 圖片

response: { type: "url", format: "png", size: "og-image" }
// <meta property="og:image" content={data.content} />

從 CSV 批次處理（證書、發票、徽章）： orshot_batch_render_template，每行一組 modifications，設定 format: "pdf"，或迴圈呼叫 POST /v1/studio/render。

每週社群圖稿，發布為草稿供審閱： 使用 publish.status: "draft" 進行渲染，然後在使用者核准後使用 orshot_publish_social_draft 發布。

一個設計，所有尺寸： extraSizes: ["1080x1920", "1080x1080", "1200x630"]。

TikTok、Instagram 或 LinkedIn 輪播圖： 請參閱 orshot-carousel 技能。

定期自動化管線： references/recurring-automation.md。檢查工作區日誌，找出使用者已在運行的 source（n8n、Make、Zapier、SDK），並加入其中；僅在使用者尚未運行任何東西時，才提供 Orshot 工作流程。

參考檔案

按需閱讀；預設不會載入這些檔案。

檔案	使用時機
references/api-reference.md	每個 REST 端點：渲染、範本、簽署 URL、品牌資產、動態 URL、資料夾、工作流程
references/render-configuration.md	修改類型、影片選項、非同步任務、動畫、音訊、智慧調整大小、回應類型、點數
references/template-design-spec.md	透過 API 建立或編輯範本的元素結構描述
references/recurring-automation.md	n8n、Make、Zapier、Pipedream、cron 和 Orshot 工作流程操作手冊
references/integrations-and-errors.md	整合清單、錯誤碼、最佳實務
references/oauth-developer-apps.md	使用 OAuth 在 Orshot 上建置第三方應用程式
references/embed.md	白標編輯器嵌入（iframe、React、Vue）
references/migration.md	從 Bannerbear、Placid、Templated、Creatomate 或其他類似服務遷移

任何文件頁面都可以 Markdown 格式取得：https://orshot.com/docs/<path>.md。MCP 伺服器也提供 orshot://template-design-spec 和 orshot://formats。

快速參考

# 連線
openclaw mcp add orshot --url https://mcp.orshot.com/mcp --transport streamable-http --auth oauth && openclaw mcp login orshot
curl -s https://api.orshot.com/v1/me -H "Authorization: Bearer $ORSHOT_API_KEY"   # REST 檢查

# 範本
GET  /v1/studio/templates/all?page=1&limit=2

…

[為翻譯而截斷]