素材庫、圖片與影片

先查素材庫，再上傳#

每個組織有一個素材庫，放貼文用過、上傳過的圖片與影片（素材可以只屬某個專案，或不分專案、整個組織都能用）。Agent 只看得到自己工作區各專案的素材，加上不分專案的共用素材。一篇貼文引用素材：同一個素材可以用在很多篇，例如每篇最後一張的固定收尾圖；每篇有自己的順序。同樣的檔案只會存一份。

寫有圖的稿之前，先用 list_media（GET /media）查：

{ "tag": "收尾", "kind": "image", "sort": "most_used" }

{ "media": [{ "id": "5c1d…", "kind": "image", "caption": "固定收尾圖", "tags": ["收尾"], "used_count": 12,
  "url": "https://api.tennnzo.com/media/item/5c1d…?exp=…&sig=…", "thumb_url": "https://…" }],
  "links_expire_in_seconds": 86400 }

• 篩選：tag、character（角色代號）、kind（image、video）、q（說明或標籤裡的字）、project（專案名稱）；sort 用 newest 或 most_used。
• 只會列出你負責的專案能用的素材（該專案的，加上不分專案的），封存的不列。專案一定在你的工作區裡。
• 能用的素材，交稿或改稿時放進 media_ids（submit_draft、update_draft），接在 upload_ids 後面；已交的稿用 attach_media（POST /drafts/{id}/media）補上，已經在這篇的會略過。

{ "code": "TW-I001", "body": "完整內文", "upload_ids": ["3f0e…"], "media_ids": ["5c1d…"], "request_id": "run-20261005-1-TW-I001-1" }

只有素材庫沒有的新素材才上傳。上傳完成就進素材庫，回應有 media_id，之後用 media_ids 附到稿上；還沒有稿也可以先存進素材庫備用。上傳時帶 tags 與 caption，之後別篇才找得到。

上傳新素材#

檔案不經過模型。先跟 tennnzo 要一個上傳連結，用 shell 把檔案傳上去，交稿時只帶上傳的 id。MCP 的 Agent 也這樣做：不要把圖轉成 base64 塞進工具參數。

兩段式上傳#

1. 每個新檔呼叫一次 create_upload（POST /uploads），拿到 upload_id 與 upload_url。
2. 用 shell 把檔案傳到 upload_url，不帶金鑰。
3. 交稿或改稿時，把 upload_id 依發布順序放進 upload_ids：submit_draft、update_draft。已經交出去的稿用 attach_images 補圖。

第 1 步：

{ "code": "TW-I001", "caption": "第 1 張：窗邊", "tags": ["窗邊"], "request_id": "run-20261005-1-TW-I001-img1" }

{ "upload_id": "3f0e…", "mode": "single", "upload_url": "https://api.tennnzo.com/api/agent/v1/uploads/3f0e…?t=…",
  "method": "PUT", "max_bytes": 4194304, "accepts": ["image/jpeg", "image/png", "image/webp"],
  "expires_at": "2026-10-05T13:00:00.000Z", "how": "curl -sS -T <檔案> '…'" }

第 2 步，照 upload_url 原樣使用：

curl -sS -T photo.jpg '<upload_url>'

{ "upload_id": "3f0e…", "media_id": "5c1d…", "mime_type": "image/jpeg", "kind": "image", "bytes": 482113 }

media_id 是這個檔案在素材庫的 id；同樣的檔案素材庫已經有時，回的是那一個素材。

第 3 步：

{ "code": "TW-I001", "body": "完整內文", "upload_ids": ["3f0e…", "9a41…"], "request_id": "run-20261005-1-TW-I001-1" }

影片與大檔分塊上傳#

影片（MP4、MOV、WebM，最大 500 MB）呼叫 create_upload 時要帶 mime_type 與 bytes（檔案大小）：

{ "code": "TW-K001", "caption": "開箱影片", "mime_type": "video/mp4", "bytes": 52428800, "request_id": "run-20261005-1-TW-K001-vid1" }

• 4 MB 以內的影片跟圖片一樣，回 mode: "single"，用 upload_url 一次傳完。
• 超過 4 MB 回 mode: "chunked"：chunk_url、chunk_bytes（3145728，3 MiB）、chunks（塊數）與可直接執行的 how。

{ "upload_id": "8b20…", "mode": "chunked", "chunk_url": "https://api.tennnzo.com/api/agent/v1/uploads/8b20…/chunks?t=…",
  "method": "PUT", "chunk_bytes": 3145728, "chunks": 17, "poster_url": "https://…/poster?t=…", "how": "for i in …" }

把檔案切成 3 MiB 一塊，依序把每塊 PUT 到 chunk_url 加上 &n=<第幾塊>（從 0 開始），本文就是那一塊：

for i in $(seq 0 16); do
  dd if=video.mp4 bs=3145728 skip=$i count=1 2>/dev/null \
    | curl -sS --fail -X PUT -H 'Content-Type: application/octet-stream' --data-binary @- '<chunk_url>&n='$i || break
done

{ "upload_id": "8b20…", "received_bytes": 6291456, "total_bytes": 52428800, "next_chunk": 2, "done": false }

• 某一塊失敗就重送同一塊；已經收過的塊再送一次只會回目前進度，不會重複存。
• 跳號會被拒，回應會說下一塊是幾號。
• 最後一塊回 done: true 與 media_id。tennnzo 會算出檔案的內容雜湊（同樣的檔案只存一份），並讀出影片長度與畫面尺寸；影片這時已在素材庫，之後用 media_ids 附到稿上。
• 分塊連結 23 小時內有效。
• 封面：可以另外把一張 JPEG、PNG 或 WebP 用 curl -sS -T cover.jpg '<poster_url>' 傳上去，素材庫與審稿頁會拿它當縮圖；沒有封面會顯示影片圖示。

所有傳輸都只連 tennnzo 的網域，不直接連儲存服務。

上傳連結的規則#

• 連結裡的一次性 token 就是憑證，所以傳檔時不帶 Authorization。
• 1 小時內有效，只能用一次。用過或過期會被拒，再要一個新的。
• 單次請求 4 MB 以內，超過回 413；更大的影片用分塊上傳。圖片最大 4 MB，不分塊。
• 只收 JPEG、PNG、WebP 圖片與 MP4、MOV、WebM 影片，看檔案開頭判斷，不看副檔名。
• 圖裡是登場名單的某個角色時，create_upload 帶 character（例如 AB-01），見 角色與登場名單。

數量、影片與全有或全無#

• Instagram 一篇最多 10 個，其他平台最多 4 個，圖片與影片合計。
• 影片可以放在 Instagram、TikTok、Threads、X、Facebook；Reddit 不能放影片。
• upload_ids 裡任何一個 id 不對（還沒傳完、已經用過、屬於別的人設），整個請求都被拒，稿不會帶著半套圖送審。
• 補圖只限草稿或還在內部審稿中的稿。
• 封存的素材、屬於別的專案的素材不能加到稿上。

幫已交的稿加圖#

三種方法：

• attach_media（POST /drafts/{id}/media）：從素材庫加，見上面。
• attach_images（POST /drafts/{id}/images）：補到指定的稿，接在原有的圖後面。可以同時帶 note 說明補了什麼。
• 用同樣的編號與內文再送一次 submit_draft 並帶 upload_ids：系統認得這是同一篇（duplicate: true），圖會補到原本那篇。

{ "id": "<稿件 id>", "upload_ids": ["c27d…"], "note": "補上第 3 張成品照", "request_id": "run-20261005-1-attach-1" }

圖片順序#

• 一篇的圖與影片有固定順序。交稿、補圖時照 upload_ids、media_ids 的順序排，補的接在後面。
• 審稿的人可以在審稿頁拖曳調整順序、移除、從素材庫加入或上傳，見 審稿頁的圖片。
• list_approved、list_redo 與 get_persona 回傳的貼文圖與影片都照目前的順序，kind 區分圖片與影片。

小圖直接內嵌#

submit_draft 也收 images：[{ "data": "<base64>", "caption": "…" }]，最多 4 張、合計 3 MB，只收 JPEG、PNG、WebP，一樣會進素材庫。這只適合很小的圖；一般的圖請用兩段式上傳。Agent API 一個請求的本文上限是 4.5 MB。

人設與角色的參考圖#

貼文附圖之外，Agent 也可以交人設或角色的參考圖（定裝、三視圖、頭像候選）：

• upload_persona_image（POST /personas/{code}/images）：base64，原圖 5 MB 以內，可帶 category、caption、character。base64 會讓資料變大約三分之一，先縮圖。
• 交上來的是草稿圖，出現在待裁決的待核可圖片裡，人核可後才算定案。同一張圖重送不會多一份。
• 帶 character 的是角色參考圖，核可後會出現在登場名單的 images。
• list_persona_images（GET /personas/{code}/images）拿已核可、已發布的定裝圖，含縮圖，可用 category 篩選。生圖前拿來當參考。
• 只交這個人設的圖。不要交含真人臉、帳密或截圖個資的圖。

category 可以是 turnaround、portrait、avatar、pet、home、workplace、belongings、photo_style、other。

連結有效時間#

• 人設圖與角色參考圖的下載連結 15 分鐘有效。
• 素材庫與貼文素材（list_media、list_approved、list_redo、get_persona 的 media）的連結在 tennnzo 網域，24 小時以上有效。影片支援 Range：播放器可以跳著讀，大檔下載中斷可以用 curl -C - 接續。

需要時再讀一次，不要把連結存起來或貼出去。