準備圖片上傳
從真實 prepare_image_upload 工具生成輸入、輸出、OAuth 權限與安全註解，與經過核實的 MCP 契約保持一致。
本頁目錄
工具
prepare_image_upload
建立短期上傳會話；客戶端按返回的方法和請求頭上傳準確位元組，再完成上傳。本地路徑不能替代檔案傳輸。
權限與安全
OAuth 權限：files:write
| 訊號 | 值 |
|---|---|
destructiveHint |
false |
idempotentHint |
false |
openWorldHint |
true |
readOnlyHint |
false |
| spendsCredits | false |
| requiresUserConfirmation | false |
| sideEffects | temporary_upload_created |
註解用於描述安全屬性，不能替代使用者批准、OAuth 授權或服務端校驗。
輸入引數
| 欄位 | 型別 | 必填 | 預設值 | 約束 | 含義 |
|---|---|---|---|---|---|
byte_size |
integer |
是 | — | exclusiveMinimum: 0 |
客戶端將通過 PUT 傳送的準確位元組數。 |
filename |
string |
是 | — | minLength: 1; maxLength: 240 |
客戶端檔名，不是服務端可以讀取的本地路徑。 |
mime_type |
string |
是 | — | pattern: ^image/(png|jpeg|webp)$ |
圖片實際 MIME 型別。 |
引數示例
{
"byte_size": 1024,
"filename": "character.png",
"mime_type": "image/png"
}
結構化返回
| 欄位 | 型別 | 必填 | 預設值 | 約束 | 含義 |
|---|---|---|---|---|---|
expires_at |
string |
是 | — | format: date-time |
上傳 URL 過期時間。 |
headers |
object |
是 | — | — | 實際傳輸請求頭，不額外新增 MCP Token 或 API Bearer 憑據。 |
max_bytes |
integer |
是 | — | — | 允許上傳的最大位元組數。 |
method |
string |
否 | "PUT" |
const: "PUT" |
客戶端傳輸位元組時必須使用的 HTTP 方法。 |
upload_id |
string |
是 | — | format: uuid |
傳給 complete_image_upload 的上傳會話 ID，不是最終 file_id。 |
upload_url |
string |
是 | — | — | 敏感短期上傳 URL，需傳輸實際位元組，不公開此地址。 |
錯誤與後續步驟
工具錯誤包含 error 物件，內有 code、message、retryable、request_id 和 details。不要依賴訊息文本分支或洩露私有輸入。終態失敗也要檢查部分產物；返回簽名 URL 不代表已儲存檔案。
這篇文件有幫助嗎？
不收集搜尋字詞、程式碼或自由文字。此開關僅控制文件互動事件。 隱私權政策