API 參考

檔案上傳策略

GET/v1/media/upload-policy

POST/v1/media/upload-policy

將圖片、影片、音訊和一般檔案上傳到檔案儲存，再把回傳的公開網址傳給模型請求。閘道只簽發綁定使用者的短期上傳憑證，檔案內容不會經過 API 伺服器。

GET /v1/media/upload-policy

{
  "image_max_bytes": 52428800,
  "video_max_bytes": 209715200,
  "audio_max_bytes": 104857600,
  "file_max_bytes": 52428800
}

#建立上傳憑證

kindstring必填
"image"、"video"、"audio" 或 "file"。
content_typestring必填
與 kind 相符的具體 MIME 類型。file 接受非圖片、影片、音訊類型，例如 application/pdf 或 text/plain。
sizeinteger必填
檔案的精確位元組數。使用同一個 API 金鑰對此端點發送 GET，可讀取該使用者生效的四類上傳上限。

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

policy.json

{
  "upload_url": "https://uploads.example.com/",
  "public_url": "https://media.example.com/media/user-upload/image/...",
  "fields": {
    "key": "media/user-upload/image/...",
    "policy": "...",
    "...": "Pass every returned field unchanged"
  },
  "expires_at": "2026-07-25T10:05:00Z"
}

#上傳到檔案儲存

把回傳的所有 fields 欄位和檔案透過一次 multipart POST 傳送到 upload_url。憑證五分鐘後過期，只能寫入一個系統產生的檔案路徑，並且不能覆蓋已有檔案。

# Save the policy response as policy.json first.
upload_args=()
while IFS=$'\t' read -r key value; do
  upload_args+=(-F "$key=$value")
done < <(jq -r '.fields | to_entries[] | [.key, .value] | @tsv' policy.json)

# Keep the file field last for storage compatibility.
curl "$(jq -r .upload_url policy.json)" \
  "${upload_args[@]}" \
  -F "file=@reference.avif"

#使用公開網址

檔案儲存回傳成功後，把 public_url 填入所選模型支援的媒體欄位。上傳介面接受某種格式，並不代表每個模型都能解碼該格式；請以模型請求契約為準。

image-task.json

{
  "model": "gpt-image-2",
  "prompt": "Turn this reference into a watercolor",
  "images": ["https://media.example.com/media/user-upload/image/..."]
}

#相關錯誤碼

該端點透過 error.type 而不是 error.code 表示失敗原因，請結合狀態碼按下列取值判斷。

400 invalid_request_errorkind、content_type 和 size 必須共同描述一個上傳檔案。
401 unauthorizedBearer 權杖無效或缺失。
413 payload_too_large宣告的檔案大小超過後台設定的上傳上限。
415 unsupported_media_typecontent_type 與所選圖片、影片、音訊或一般檔案分類不符。

完整錯誤碼表 →

還是沒解決？

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