BUILT TO CONNECT

創作有自己的工具。
發布有共同的接口。

把影片、封面、字幕與文案交給 Publish。
從保存、驗證到定時分享，讓人與 AI 都接得上。

開始串接取得 OpenAPI

REST API v1OpenAPI 3.1MCP · 唯讀查詢

ONE DELIVERY, EVERY STEP RECORDED

你的創作工具

影片 + 封面 + 雙語字幕 + 平台文案

保存與驗證

可續傳上傳 · 檔案雜湊 · 來源記錄

安排發布，取得結果

立即 · 指定時間 · 加入佇列

6個交付端點2個 MCP 查詢工具3種發布安排AI agent 完整指南

01 / QUICK START

先建立信任，再交付內容。

文件公開，發布權限由站長授予。應用 Token 只連到選定帳號與自己的交付包，不等同後台管理權限。

建立專用應用

站長登入後，到「設定 → API 應用程式」命名並勾選帳號。Token 只顯示一次，可隨時撤銷。

前往應用設定

放進後端秘密設定

建議使用 PUBLISH_API_TOKEN。每次透過 Bearer 標頭傳送，不放進瀏覽器、網址或對話。

讀取實際帳號能力

先取得 channel_id、媒體能力與限制。這個查詢不發文，也不呼叫付費社群接口。

cURL · 第一個唯讀請求

curl --fail-with-body --max-time 30 \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN" \
  https://publish.zuola.com/api/v1/integrations/clip/capabilities

一般訪客無法自行取得發布權限。需要為你的工具串接服務？聯絡討論需求。

02 / DELIVERY WORKFLOW

內容先保存。時間，由你決定。

目前對外 API 以影片交付包為主；任何獲授權的後端都可使用，路徑中的 clip 保留既有相容性。純文字草稿、訂閱與留言管理仍在後台操作。

建立包
分段上傳
完成驗證
明確排程
查詢結果

兩個狀態，不能混為一談

202 表示正在驗證；ready 表示檔案已保存。只有各目標的 state=published 才表示該平台確認發布成功。

連結按順序準備好

同一計畫先 YouTube，再 WordPress，最後其他社群。下游等待確認的影片與官網連結，分享網址由 Publish 縮短。

來源政策一起交付。原創影片可在同一計畫搭配 YouTube 發到 WordPress；Feed 衍生內容永遠不能回寫 WordPress。不能用改標籤或改寫文案解除限制。

03 / REST API

六個端點，走完一次交付。

Base URL：https://publish.zuola.com/api/v1/integrations/clip

GET/capabilities取得帳號與能力

只回傳本應用允許的帳號、格式、字幕與上傳限制。先讀這個接口，再決定要交付哪些版本。

200 · channels、schedule_modes、chunk_bytes、max_file_bytes_by_role

POST/packages建立交付包

提交影片、封面、字幕與平台文案的 manifest。帶上穩定的 Idempotency-Key；保存回傳的包 ID 和檔案上傳路徑。

201 新建／200 重用 · id、version、files[].upload_path、offset

PUT/packages/{id}/files/{key}分段上傳與續傳

傳送原始二進位資料，每段最多 8 MiB。附上 Content-Range 與精確 Content-Length；下一段從回傳的 offset 繼續。

200 · offset；409 · upload_offset_conflict、expected_offset

POST/packages/{id}/complete開始完整性驗證

帶上 expected_version 與 Idempotency-Key。後台會核對檔案長度、雜湊、媒體及字幕關聯；202 只是接受驗證。

202 · 包收據；接著輪詢，等待 storage_committed=true 且 state=ready

POST/packages/{id}/schedule明確安排發布

選擇 now、at 或 queue，帶入最新版本、各目標的 channel_id／version_key，以及獨立的 Idempotency-Key。這一步才建立發布任務。

201 新排程／200 重用 · targets[].id、channel_id、scheduled_at

GET/packages/{id}持續追蹤結果

取得續傳進度、驗證狀態及各平台結果。建議每 5 秒查詢並設停止條件；waiting_dependency 代表仍在等前置平台。

200 · files、version、storage_committed、targets[].state／remote_url／last_error

所有業務請求都需要 Token。完整欄位、型別與回應結構見 OpenAPI JSON；REST 寫入不接受瀏覽器 Origin，不提供前端直接持有 Token 的整合模式。

04 / REQUEST EXAMPLES

從可以讀懂的請求開始。

Node.js · 後端讀取能力

// 在你的後端執行；Token 由伺服器秘密設定注入。
const response = await fetch(
  "https://publish.zuola.com/api/v1/integrations/clip/capabilities",
  {
    headers: { Authorization: "Bearer " + process.env.PUBLISH_API_TOKEN },
    signal: AbortSignal.timeout(30_000),
    redirect: "error",
  }
);
if (!response.ok) throw new Error("Publish HTTP " + response.status);
const { channels, chunk_bytes } = await response.json();
// 保存實際 channel_id，依帳號能力選擇媒體版本。

建立交付包 · manifest 範例

POST /packages，附上 Idempotency-Key。下方大小與全零雜湊僅為占位，必須替換成檔案真實 byte 長度與 SHA-256；平台版本以實際需要為準。

JSON · 最小影片包

{
  "schema_version": 1,
  "external_id": "editor:project-42:render-3",
  "project_id": "project-42",
  "rendition_id": "render-3",
  "source_kind": "original",
  "source_refs": [],
  "content": {
    "title": "這次創作的標題",
    "body": "這支影片想分享的故事。",
    "language": "zh-Hant"
  },
  "files": [
    {
      "key": "video",
      "role": "video",
      "mime": "video/mp4",
      "bytes": 1024,
      "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
      "rendition_id": "render-3"
    }
  ],
  "versions": [
    {
      "key": "threads-main",
      "provider": "threads",
      "video_key": "video"
    }
  ]
}

指定時間發布 · 排程範例

POST /packages/{id}/schedule。使用收據中的最新版本、實際帳號 ID 及使用者指定的未來時間。now 與 queue 不傳 scheduled_at。

JSON · mode=at

{
  "expected_version": 3,
  "mode": "at",
  "scheduled_at": "2030-06-01T18:00:00+08:00",
  "timezone": "Asia/Taipei",
  "targets": [
    {
      "channel_id": "CHANNEL_ID_FROM_CAPABILITIES",
      "version_key": "threads-main"
    }
  ]
}

封面與字幕各自列在 files，再由版本引用 cover_key／subtitle_keys。分段上傳的精確標頭、續傳和輪詢示例，請讀完整串接指南。

05 / MCP FOR AGENTS

讓 AI 看懂能力，也查得到進度。

真正的 MCP 入口，使用 Streamable HTTP、無持久 session 與 JSON 回應。沿用同一個應用 Token，每次查詢都重新驗證權限。

publish_capabilities

讀取允許帳號、媒體能力與上傳限制。

{}

publish_package_status

查自己的交付包與每個目標的結果。

{"package_id":"包 ID"}

MCP · 通用客戶端設定示意

{
  "mcpServers": {
    "publish-zuola": {
      "url": "https://publish.zuola.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PUBLISH_API_TOKEN"
      }
    }
  }
}

以客戶端的私密設定替換 Token 占位，不把實際值貼進公開設定檔。需要支援自訂 Authorization 標頭；只支援 OAuth 的 MCP 客戶端請改用 REST。

先探索，再呼叫

工具結構由 tools/list 取得；resources/read 可讀 publish://integration。協議由官方 Go MCP SDK 處理。

本版 MCP 僅供查詢

不含上傳、發布、取消或留言回覆工具。影片檔走 REST 二進位傳輸；建立排程仍是使用者明確授權的 API 操作。

06 / RELIABLE BY DESIGN

斷線能接續。結果可核對。

固定重試身分

建立包、完成驗證及排程各有穩定的 Idempotency-Key。相同請求重用同一個 key；回應遺失時先查收據，不建立第二份任務。

隔離與保留

每應用只操作自己的包。撤銷 Token 後停止存取；已建立排程與保存素材仍保留，更換應用不會接管舊包。

目前上傳與呼叫限制；平台限制可能更嚴格
項目	限制
每應用 API + MCP	600 次／分鐘；429 遵循 Retry-After
每個包	最多 32 檔，合計 8 GiB
每支影片 / 每張封面	2 GiB / 25 MiB
每份字幕 / 每段上傳	100,000 bytes / 8 MiB
MCP 請求	64 KiB；無獨立 GET / SSE 串流

錯誤處理與發布狀態

401 / 403：檢查 Token、Origin 與帳號允許清單。
404：包或檔案不存在，或不屬於本應用。
409：版本、offset、狀態或去重衝突；先讀目前收據。
413 / 422：大小、格式、時間或來源政策不符；修正輸入。
429 / 5xx：依錯誤原因有限退避；不能盲目重送發布。
unknown：遠端結果不明，交由後台核對，不當成未發布。
MCP 即使 HTTP 200，也須檢查 result.isError。

Go 處理 API 與背景工作，SQLite 保存排程、收據與重試進度，前端靜態輸出。平台能力由各 adapter 分開檢查，不承諾每個平台接受相同媒體或提供相同互動功能。

07 / READY FOR YOUR AGENT

把這段交給你的開發助手。

提供公開文件與工作要求即可。Token 留在你自己的後端秘密設定中。

可複製的串接指令

請為我的應用串接 Publish Zuola。

先讀取：
https://publish.zuola.com/openapi.json
https://publish.zuola.com/llms-full.txt

使用後端秘密 PUBLISH_API_TOKEN；不要把 Token 放入前端、對話、Git 或日誌。
先查 capabilities，使用真實的 channel_id。實作不可變交付版本、檔案 SHA-256、分段續傳與收據保存。
完成驗證後，只有使用者明確選取帳號與時間，才建立 now／at／queue 排程。上傳本身不發布。
保留 Feed 來源及 WordPress 封鎖；不要為了重試建立重複發布任務。
可透過 MCP 查能力與進度，寫入仍用 REST API。自動化測試全部使用 mocks，不發真實貼文。

llms.txt 完整 AI 指南 OpenAPI JSON

MAKE IT PART OF YOUR WORKFLOW

你的工作流程，也可以接上。

內容製作、影片交付與多平台排程，從具體需求開始討論。

討論串接需求