按能力

上傳檔案

當客戶端只有本機的圖片、影片、音訊、PDF、試算表或其他檔案時，請使用平台檔案上傳流程。API 會回傳臨時上傳位址和穩定的 public_url，客戶端無需在意檔案儲存的具體實作。

#選擇公開網址、上傳或 Base64

現有輸入	建議方式	原因
已有公開 HTTPS 網址	直接傳送網址	無需重複上傳，請求主體也最小。
裝置上的本機檔案	先上傳，再傳送 public_url	適合大檔案，並可在重試時重複使用。
小型內嵌圖片，且模型明確支援 Base64	可以使用 Base64	僅在所選模型契約明確允許時使用。

#本機檔案上傳流程

1
讀取目前上限
使用同一個 API 金鑰，以套用該使用者的專屬上限。
GET /v1/media/upload-policy
2
建立上傳憑證
傳送 kind、明確的 content_type 和精確位元組數。
POST /v1/media/upload-policy
3
上傳檔案
將所有回傳的 fields 欄位和檔案一起 POST 到 upload_url。
multipart/form-data
4
使用回傳的網址
將 public_url 放入模型支援的媒體欄位。
public_url

create-policy.sh

curl https://www.aisplice.store/v1/media/upload-policy \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "file",
    "content_type": "application/pdf",
    "size": 1048576
  }'

#將上傳欄位視為不透明資料

原樣傳送 fields 回傳的每一個鍵值，不要重新命名、過濾或快取。上傳憑證有效期很短，並綁定到唯一產生的檔案路徑。

browser.ts

const form = new FormData();
for (const [key, value] of Object.entries(policy.fields)) {
  form.append(key, String(value));
}
form.append("file", file); // keep the file field last

const uploaded = await fetch(policy.upload_url, {
  method: "POST",
  body: form,
});
if (!uploaded.ok) throw new Error(await uploaded.text());

const modelInputUrl = policy.public_url;

#檔案類型與模型支援

上傳成功不代表模型可以讀取

上傳介面可以儲存 PDF、Excel、文字等一般檔案，但只有模型請求契約宣告了相符的檔案或網址欄位時，模型才能讀取。僅支援圖片的模型不會因為試算表有公開網址就能讀取它。

檢視所選模型的請求契約

全部欄位：見 API 參考裡的 /v1/media/upload-policy →

還是沒解決？

把請求 ID 或錯誤訊息傳給我們，我們來查。