上傳檔案

從你的服務端上傳訊息附件、使用者頭像、群頭像、聊天室封面和群檔案，例如以系統賬號發圖片通知、匯入使用者時設定頭像、往群檔案裡放資料。用途、大小上限、格式和保留規則見檔案概述。

上傳分三步：

建立上傳，得到上傳地址；
直接向物件儲存上傳檔案內容；
完成上傳，得到檔案地址。

檔案大小	方式
不超過 32 MB	單次上傳：建立時返回一個上傳地址，一次 `PUT` 寫入
超過 32 MB	分片上傳：每 16 MB 一片，先索取分片上傳地址再逐片上傳；中斷後查詢已上傳的分片從斷點繼續

本頁先給出兩個完整的示例，再逐個說明各介面。

客戶端上傳

使用者在客戶端上傳時，由客戶端用 User Token 呼叫與本頁相同的介面，路徑字首為 /client/v1/media（如 POST /client/v1/media/uploads），流程和引數相同，只是不能指定 owner（所屬使用者就是上傳者本人），按使用者限制頻率，上傳群檔案還要求是群成員。SDK 釋出後由 SDK 封裝，客戶端傳送圖片訊息、更換頭像不需要經過你的服務端。

上傳圖片併傳送訊息

以 alice 的身份給 bob 傳送一張圖片。

1. 建立上傳。 圖片 photo.jpg 的大小為 269867 位元組：

bash

curl -X POST "$IM_API/$ORG/$APP/media/uploads" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "attachment",
    "kind": "image",
    "size": 269867,
    "content_type": "image/jpeg",
    "name": "photo.jpg"
  }'

json

{
  "file_id": "99606093402996736",
  "upload_method": "single",
  "upload": {
    "url": "https://storage.example.com/im-private/staging/t99604914749046784/a99604957103128576/99606093402996736?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Date=20261002T203903Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=content-length%3Bhost&X-Amz-Signature=a5900ffd...",
    "method": "PUT",
    "headers": { "Content-Length": "269867" }
  },
  "part_size": null,
  "part_count": 0,
  "expires_at": "2026-10-02T21:39:03.259Z"
}

2. 上傳檔案內容。 用返回的 upload.method 請求 upload.url，請求體為檔案內容。curl --upload-file 會自動帶上 Content-Length：

bash

curl -X PUT "https://storage.example.com/im-private/staging/t99604914749046784/a99604957103128576/99606093402996736?X-Amz-Algorithm=AWS4-HMAC-SHA256&...&X-Amz-Signature=a5900ffd..." \
  --upload-file photo.jpg

物件儲存返回 200 OK，沒有響應體。

3. 完成上傳。

bash

curl -X POST "$IM_API/$ORG/$APP/media/uploads/99606093402996736/complete" \
  -H "Authorization: Bearer $APP_TOKEN"

返回檔案物件。圖片去掉了拍攝資訊等後設資料，size 比原檔案略小：

json

{
  "file_id": "99606093402996736",
  "purpose": "attachment",
  "kind": "image",
  "status": "active",
  "url": "https://im.example.com/media/v1/f/99606093402996736/DC0neNm6HBbxGW9bN6g_iA",
  "thumbnail_url": "https://im.example.com/media/v1/f/99606093402996736/DC0neNm6HBbxGW9bN6g_iA/thumb",
  "name": "photo.jpg",
  "content_type": "image/jpeg",
  "size": 269803,
  "width": 1080,
  "height": 720,
  "owner": null,
  "group_id": null,
  "via": "openapi",
  "created_at": "2026-10-02T20:39:03.259Z",
  "expires_at": "2026-11-01T20:39:03.259Z",
  "in_use": false,
  "sha256": "6c458b05f583eca6c08cd7296ec4d2811c68cf59cbc3c8b30feeb8cdc45994ef",
  "created_by": "99604957107322880",
  "blocked_at": null,
  "blocked_by": null,
  "block_rule_source": null,
  "block_reason": null,
  "deleted_at": null,
  "delete_reason": null
}

4. 傳送圖片訊息。 把檔案物件中的 url、thumbnail_url、width、height、size 寫進圖片訊息的 body，format 按 content_type 填寫。圖片訊息的 body 中只有 url 是必填的，其他欄位用於客戶端在下載之前排版和顯示，建議都填上。各型別訊息的 body 見訊息型別，傳送介面見傳送訊息：

bash

curl -X POST "$IM_API/$ORG/$APP/messages" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "alice",
    "to_user": "bob",
    "client_msg_id": "img-0001",
    "type": "image",
    "body": {
      "url": "https://im.example.com/media/v1/f/99606093402996736/DC0neNm6HBbxGW9bN6g_iA",
      "thumbnail_url": "https://im.example.com/media/v1/f/99606093402996736/DC0neNm6HBbxGW9bN6g_iA/thumb",
      "width": 1080,
      "height": 720,
      "size": 269803,
      "format": "jpg"
    }
  }'

bob 的客戶端收到訊息後，用 User Token 換取縮圖和原圖的下載地址後顯示，見檔案地址。

訊息中要寫檔案地址，不要寫換取得到的下載地址：下載地址最長 90 分鐘後失效。
同一個檔案可以發到多個會話中，不需要重複上傳。附件從上傳時起按 attachment_retention_days（預設 30 天）保留，到期後訊息仍在，下載時提示檔案已過期。
檔案訊息（type 為 file）的 body 中 name 也是必填的，通常填上傳時的檔名；語音和影片訊息還要填 duration_seconds，服務端不解析音影片，由你填寫時長。影片的封面請另外作為圖片上傳，填寫它的地址。

為使用者設定頭像

使用者頭像要先上傳，再用得到的公開地址修改使用者資料。上傳時必須用 owner 指定使用這個頭像的使用者，所以匯入使用者時先建立使用者（不帶頭像），再上傳頭像，最後修改資料。

1. 建立上傳，用途為 user_avatar：

bash

curl -X POST "$IM_API/$ORG/$APP/media/uploads" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "user_avatar",
    "kind": "image",
    "size": 43484,
    "content_type": "image/jpeg",
    "owner": "carol"
  }'

2. 上傳檔案內容，與上例相同：

bash

curl -X PUT "<upload.url>" --upload-file avatar.jpg

3. 完成上傳，得到頭像的公開地址。1200 × 1200 畫素的原圖被縮放為 640 × 640：

bash

curl -X POST "$IM_API/$ORG/$APP/media/uploads/99606376459796480/complete" \
  -H "Authorization: Bearer $APP_TOKEN"

json

{
  "file_id": "99606376459796480",
  "purpose": "user_avatar",
  "kind": "image",
  "status": "active",
  "url": "https://cdn.example.com/t99604914749046784/a99604957103128576/u/99606376459796480_thhts5lb.jpg",
  "thumbnail_url": null,
  "name": null,
  "content_type": "image/jpeg",
  "size": 14083,
  "width": 640,
  "height": 640,
  "owner": "carol",
  "group_id": null,
  "via": "openapi",
  "created_at": "2026-10-02T20:40:10.745Z",
  "expires_at": null,
  "in_use": false,
  "sha256": "2c1638f06c486e40ad416456ccd8dd3cae5d34d6c2e6350b87fbcf421d3a66b5",
  "created_by": "99604957107322880",
  "blocked_at": null,
  "blocked_by": null,
  "block_rule_source": null,
  "block_reason": null,
  "deleted_at": null,
  "delete_reason": null
}

4. 修改使用者資料，見修改使用者資料：

bash

curl -X PATCH "$IM_API/$ORG/$APP/users/carol" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar_url": "https://cdn.example.com/t99604914749046784/a99604957103128576/u/99606376459796480_thhts5lb.jpg"
  }'

修改後片刻，查詢檔案可以看到這個頭像的 in_use 變為 true。

上傳後 24 小時內沒有設定到資料中的頭像會被自動刪除；
之後再更換頭像，原來的頭像在 7 天后刪除，不需要你處理；
使用者頭像只能用於 owner 本人的資料，設定給其他使用者不算使用，到期同樣會被刪除；
群頭像的流程相同：用途為 group_avatar，不需要 owner，完成後用公開地址修改群資料的 avatar_url；
聊天室封面的流程也相同：用途為 chatroom_avatar，不需要 owner，完成後用公開地址建立聊天室或修改聊天室資料的 avatar_url。聊天室解散 7 天后，封面被刪除。

建立上傳

宣告要上傳的檔案，得到檔案 ID 和上傳地址。服務端檢查用途和型別的組合、大小上限和應用的儲存額度，不檢查檔案的內容：內容在完成上傳時檢查。每次呼叫都建立一個新的上傳，不去重；沒有完成的上傳到期後自動刪除，不計入儲存用量。

你的服務端上傳群檔案時只檢查群存在且沒有解散，不檢查 owner 是否為群成員，不受執行策略 group_file_enabled 和群封禁的限制。應用處於只讀狀態時不能建立上傳，但已經建立的上傳仍可以完成。

POST/{org_name}/{app_name}/media/uploads

路徑引數

org_name、app_name 見接入概述。

請求體

欄位	型別	必填	說明
`purpose`	String	是	用途：`attachment` 訊息附件 / `user_avatar` 使用者頭像 / `group_avatar` 群頭像 / `chatroom_avatar` 聊天室封面 / `group_file` 群檔案，見檔案的用途
`kind`	String	是	型別：`image`、`voice`、`video`、`file`。訊息附件可以是全部四種，頭像和聊天室封面只能是 `image`，群檔案可以是 `image`、`video`、`file`。完成上傳時按檔案內容檢查格式是否符合型別，見格式檢查與圖片處理
`size`	Number	是	檔案大小，位元組，大於 0。上傳的內容必須恰好是這麼多位元組。上限：訊息附件和群檔案為執行策略 `max_upload_bytes`（預設 100 MB），其中圖片不超過 20 MB、語音不超過 5 MB（`max_upload_bytes` 更小時取它）；頭像和聊天室封面為 5 MB
`content_type`	String	否	檔案的格式（MIME 型別），如 `image/jpeg`，最長 128 個字元。只作參考，格式以完成上傳時按檔案內容識別出的為準
`name`	String	視情況	檔名，最長 255 個字元，規則與檔案訊息的 `name` 相同。型別為 `file` 的檔案和群檔案必填，其他可選。下載 `file` 型別的檔案和群檔案時作為儲存的檔名
`group_id`	String	群檔案必填	群 ID。只有群檔案可以帶，群必須存在且沒有解散
`owner`	String	使用者頭像必填	所屬使用者的使用者名稱，使用者必須存在。使用者頭像為使用這個頭像的使用者，只有他的資料能使用它；其他用途可選，用於記錄檔案屬於哪個使用者，例如代使用者上傳的附件。應用開啟了刪除使用者時擦除訊息（`erase_messages_on_user_delete`）的，刪除這個使用者時他的附件和群檔案隨之刪除

請求示例

上傳一個 35 MB 的影片（超過 32 MB，分片上傳）：

bash

curl -X POST "$IM_API/$ORG/$APP/media/uploads" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "attachment",
    "kind": "video",
    "size": 36712345,
    "content_type": "video/mp4",
    "name": "发布会.mp4"
  }'

向群檔案中上傳一份 PDF，記為 bob 上傳的：

bash

curl -X POST "$IM_API/$ORG/$APP/media/uploads" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "group_file",
    "kind": "file",
    "size": 3145728,
    "name": "Q3 需求评审.pdf",
    "group_id": "99606031272771584",
    "owner": "bob"
  }'

響應

成功返回 201 Created：

欄位	型別	說明
`file_id`	String	檔案 ID，之後的上傳介面和檔案介面都用它
`upload_method`	String	上傳方式：`single` 單次上傳，按 `upload` 一次上傳全部內容；`multipart` 分片上傳，按 `part_size` 分片後逐片上傳。由服務端按 `size` 決定，超過 32 MB 的為 `multipart`
`upload`	Object	單次上傳的上傳地址，分片上傳為 `null`。用法見上傳檔案內容
`upload.url`	String	上傳地址，1 小時內有效
`upload.method`	String	請求方法，固定為 `PUT`
`upload.headers`	Object	上傳時必須帶的請求頭，目前為 `Content-Length`，值與 `size` 相同
`part_size`	Number	分片上傳時每片的大小，固定為 16777216（16 MB），最後一片為剩餘的部分；單次上傳為 `null`
`part_count`	Number	分片數，即 `size` 除以 16 MB 向上取整；單次上傳為 `0`
`expires_at`	String	上傳的有效期：單次上傳為 1 小時後，分片上傳為 24 小時後。到期仍未完成的上傳自動作廢

分片上傳的響應：

json

{
  "file_id": "99606786000027648",
  "upload_method": "multipart",
  "upload": null,
  "part_size": 16777216,
  "part_count": 3,
  "expires_at": "2026-10-03T20:41:48.387Z"
}

單次上傳的響應見上傳圖片併傳送訊息。

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`details.reason` 為 `invalid_purpose`：用途不正確，或用途與型別的組合不允許
400	`invalid_argument`	`details.reason` 為 `invalid_name`：型別為 `file` 的檔案或群檔案沒有給出 `name`，或檔名不符合規則
400	`invalid_argument`	不帶 `details`：`size` 不大於 0；`content_type` 超過 128 個字元；群檔案沒有 `group_id`，或其他用途帶了 `group_id`；使用者頭像沒有 `owner`。`message` 說明了原因
403	`app_unavailable`	應用處於只讀狀態，不能上傳，見限流與應用狀態
404	`not_found`	`owner` 指定的使用者不存在或已刪除（“使用者不存在”）；群不存在或已解散（“群不存在或已解散”）
409	`limit_exceeded`	`details.reason` 為 `storage_quota`：應用的儲存額度已滿，另帶 `limit_bytes`、`used_bytes`，見儲存用量與額度；`details.reason` 為 `group_file_limit`：這個群的群檔案已滿 1000 個
413	`payload_too_large`	`size` 超過這種用途和型別的大小上限，`details.max_bytes` 為上限的位元組數

json

{
  "error": {
    "code": "payload_too_large",
    "message": "文件超过大小上限",
    "details": { "max_bytes": 20971520 },
    "request_id": "VRKDMUL77JAZIGGSWDSE5V7GBE"
  }
}

上傳檔案內容

檔案內容直接上傳到物件儲存，不經過 IM 服務的介面。上傳地址已經帶有簽名，請求時不要帶 Authorization 請求頭。

單次上傳：用 upload.method（PUT）請求 upload.url，帶上 upload.headers 中的全部請求頭，請求體為檔案的全部內容。
分片上傳：對每一片，用索取分片上傳地址返回的 method、url 和 headers 上傳這一片的內容。第 N 片是檔案中從第 (N − 1) × 16 MB 個位元組開始的 16 MB，最後一片為剩餘的部分。各片可以並行、按任意順序上傳。

注意：

請求必須帶 Content-Length，且與簽名中的長度（size 或這一片的大小）完全相同。長度不同時物件儲存返回 403（SignatureDoesNotMatch）；不能使用分塊傳輸編碼（Transfer-Encoding: chunked），否則返回 411。多數 HTTP 庫按檔案或位元組陣列上傳時會自動設定 Content-Length。
Content-Type 請求頭不檢查，可以不帶，格式以完成上傳時識別的為準。
上傳成功時物件儲存返回 200 OK；失敗時返回物件儲存自己的 XML 格式的錯誤，不是本服務的錯誤結構。
上傳地址在有效期內可以重複使用：網路中斷或上傳失敗時，用同一個地址重新上傳即可，以最後一次成功上傳的內容為準。上傳地址過期後，單次上傳要重新建立上傳；分片上傳可以重新索取這一片的地址。

bash

curl -X PUT "https://storage.example.com/im-private/t99604914749046784/a99604957103128576/m/99606786000027648?X-Amz-Algorithm=AWS4-HMAC-SHA256&...&partNumber=1&uploadId=ZTBmOTBh...&X-Amz-Signature=b665663e..." \
  --upload-file part1.bin

索取分片上傳地址

為分片上傳的若干片簽發上傳地址，一次最多 100 片。可以一次索取全部分片，也可以邊上傳邊索取；地址過期後重新索取即可，已經上傳的分片不受影響。只能用於 upload_method 為 multipart 的上傳。

POST/{org_name}/{app_name}/media/uploads/{file_id}/parts

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`file_id`	String	建立上傳時返回的檔案 ID

請求體

欄位	型別	必填	說明
`part_numbers`	Array<Number>	是	片號，從 1 開始，1 到 `part_count` 之間，一次 1 到 100 個，不能重複

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/media/uploads/99606786000027648/parts" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "part_numbers": [1, 2, 3]
  }'

響應

成功返回 200 OK：

欄位	型別	說明
`parts`	Array<Object>	各片的上傳地址，按請求中的順序
`parts[].part_number`	Number	片號
`parts[].url`	String	這一片的上傳地址
`parts[].method`	String	請求方法，固定為 `PUT`
`parts[].headers`	Object	上傳這一片時必須帶的請求頭，目前為 `Content-Length`，即這一片的大小
`parts[].expires_at`	String	地址的有效期：1 小時後，但不晚於上傳的有效期

json

{
  "parts": [
    {
      "part_number": 1,
      "url": "https://storage.example.com/im-private/t99604914749046784/a99604957103128576/m/99606786000027648?X-Amz-Algorithm=AWS4-HMAC-SHA256&...&partNumber=1&uploadId=ZTBmOTBh...&X-Amz-Signature=b665663e...",
      "method": "PUT",
      "headers": { "Content-Length": "16777216" },
      "expires_at": "2026-10-02T21:41:53.960Z"
    },
    {
      "part_number": 2,
      "url": "https://storage.example.com/im-private/t99604914749046784/a99604957103128576/m/99606786000027648?X-Amz-Algorithm=AWS4-HMAC-SHA256&...&partNumber=2&uploadId=ZTBmOTBh...&X-Amz-Signature=8e08a1ca...",
      "method": "PUT",
      "headers": { "Content-Length": "16777216" },
      "expires_at": "2026-10-02T21:41:53.960Z"
    },
    {
      "part_number": 3,
      "url": "https://storage.example.com/im-private/t99604914749046784/a99604957103128576/m/99606786000027648?X-Amz-Algorithm=AWS4-HMAC-SHA256&...&partNumber=3&uploadId=ZTBmOTBh...&X-Amz-Signature=ec6fd43f...",
      "method": "PUT",
      "headers": { "Content-Length": "3157913" },
      "expires_at": "2026-10-02T21:41:53.960Z"
    }
  ]
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`part_numbers` 為空、超過 100 個、超出 1 到 `part_count` 的範圍或有重複；或者這次上傳是單次上傳，沒有分片
404	`not_found`	上傳不存在、已取消或已過期，或者不是透過本應用的 OpenAPI 建立的
409	`version_conflict`	上傳已經完成，`details.reason` 為 `upload_completed`

查詢已上傳的分片

返回分片上傳中已經上傳成功的分片，按片號升序一次返回全部。上傳中斷後，用它找出缺少的分片，只補傳這些分片，再完成上傳。只能用於分片上傳。

GET/{org_name}/{app_name}/media/uploads/{file_id}/parts

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`file_id`	String	建立上傳時返回的檔案 ID

請求示例

bash

curl "$IM_API/$ORG/$APP/media/uploads/99606786000027648/parts" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
`parts`	Array<Object>	已上傳的分片，按片號升序；還沒有上傳任何分片時為空陣列
`parts[].part_number`	Number	片號
`parts[].size`	Number	這一片已上傳的大小，位元組。除最後一片外應為 16777216，不等時請重新上傳這一片

上傳了第 1、3 片，缺少第 2 片：

json

{
  "parts": [
    { "part_number": 1, "size": 16777216 },
    { "part_number": 3, "size": 3157913 }
  ]
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	這次上傳是單次上傳，沒有分片
404	`not_found`	上傳不存在、已取消或已過期，或者不是透過本應用的 OpenAPI 建立的
409	`version_conflict`	上傳已經完成，`details.reason` 為 `upload_completed`

完成上傳

內容上傳完之後呼叫，沒有請求體；分片上傳也不需要提交分片列表，服務端自行核對已上傳的分片。服務端核對大小、按檔案內容識別格式，處理圖片和頭像（見格式檢查與圖片處理），透過後檔案變為可用，返回檔案物件。

可以重試：已經完成的上傳再次呼叫，返回 200 OK 和第一次的結果。一次完成請求最多處理 2 分鐘，超時返回 500 internal，上傳仍然有效，稍後重試即可。前一個完成請求還在處理時返回 409 version_conflict（upload_completing），稍後重試。
失敗後能否重試：內容還沒有上傳完（upload_incomplete）、處理繁忙（image_busy）、核對過程中內容被重新上傳（upload_changed）等情況，上傳仍然有效，補傳內容或稍後再次完成即可。格式不符合型別、圖片無法處理、群檔案已滿、所屬使用者已刪除、群已解散的，這次上傳隨即作廢，要重新建立上傳；之後再呼叫完成返回 400 invalid_argument（upload_failed）。
完成之後：上傳地址仍可以使用到過期，但再次上傳的內容不會改變已經完成的檔案。

POST/{org_name}/{app_name}/media/uploads/{file_id}/complete

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`file_id`	String	建立上傳時返回的檔案 ID

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/media/uploads/99606786000027648/complete" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，響應體為檔案物件。以上文分片上傳的影片為例（影片沒有縮圖和寬高，也不計算 sha256）：

json

{
  "file_id": "99606786000027648",
  "purpose": "attachment",
  "kind": "video",
  "status": "active",
  "url": "https://im.example.com/media/v1/f/99606786000027648/AIqdvqpQk8b2JOVXzRFOfA",
  "thumbnail_url": null,
  "name": "发布会.mp4",
  "content_type": "video/mp4",
  "size": 36712345,
  "width": null,
  "height": null,
  "owner": null,
  "group_id": null,
  "via": "openapi",
  "created_at": "2026-10-02T20:41:48.396Z",
  "expires_at": "2026-11-01T20:41:48.396Z",
  "in_use": false,
  "sha256": null,
  "created_by": "99604957107322880",
  "blocked_at": null,
  "blocked_by": null,
  "block_rule_source": null,
  "block_reason": null,
  "deleted_at": null,
  "delete_reason": null
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`details.reason` 為 `upload_incomplete`：單次上傳還沒有上傳內容（“檔案還沒有上傳”），或分片上傳缺少分片、某一片的大小不對（“分片不全或大小不對”）。上傳仍然有效，補傳後再次完成
400	`invalid_argument`	`details.reason` 為 `size_mismatch`：上傳的大小與 `size` 不同，`details.size` 為實際的大小。上傳仍然有效，重新上傳後再次完成
400	`invalid_argument`	`details.reason` 為 `unsupported_type`：檔案的格式不符合型別，`details.content_type` 為識別出的格式。這次上傳作廢
400	`invalid_argument`	`details.reason` 為 `image_too_large`：圖片超過 5000 萬畫素；`invalid_image`：圖片無法解碼。這次上傳作廢
400	`invalid_argument`	`details.reason` 為 `upload_failed`：這次上傳已經因為上述原因作廢，請重新建立上傳
403	`file_blocked`	檔案已完成上傳，之後因違規被遮蔽
404	`not_found`	上傳不存在、已取消或已過期，或者不是透過本應用的 OpenAPI 建立的（“上傳不存在、已取消或已過期”）；`owner` 指定的使用者在上傳期間被刪除（“使用者不存在”）；群檔案所在的群在上傳期間解散（“群不存在或已解散”）。後兩種情況這次上傳作廢
409	`version_conflict`	`details.reason` 為 `upload_completing`：另一個完成請求正在處理這個檔案；`upload_changed`：核對的過程中內容被重新上傳了。都可以稍後再次完成
409	`limit_exceeded`	`details.reason` 為 `group_file_limit`：群檔案已滿 1000 個。這次上傳作廢
429	`rate_limited`	`details.reason` 為 `image_busy`：圖片處理繁忙，按 `Retry-After` 等待後再次完成
500	`internal`	處理超時（“完成上傳超時，請稍後重試”）等內部錯誤，上傳仍然有效，稍後重試

json

{
  "error": {
    "code": "invalid_argument",
    "message": "文件的格式不符合类型",
    "details": { "content_type": "text/plain", "reason": "unsupported_type" },
    "request_id": "BN22NWAAYNNI3ERPKAWSHIBRPH"
  }
}

取消上傳

放棄一次還沒有完成的上傳，已上傳的內容隨後刪除。已經取消、過期或作廢的上傳再次取消也返回成功。已經完成的上傳不能取消，要刪除檔案請用刪除檔案。

DELETE/{org_name}/{app_name}/media/uploads/{file_id}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`file_id`	String	建立上傳時返回的檔案 ID

請求示例

bash

curl -X DELETE "$IM_API/$ORG/$APP/media/uploads/99606941961027584" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 204 No Content，沒有響應體。

錯誤

HTTP 狀態碼	`code`	說明
404	`not_found`	上傳不存在，或者不是透過本應用的 OpenAPI 建立的
409	`version_conflict`	上傳已經完成，`details.reason` 為 `upload_completed`

上傳檔案 ​

上傳圖片併傳送訊息 ​

為使用者設定頭像 ​

建立上傳 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

上傳檔案內容 ​

索取分片上傳地址 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

查詢已上傳的分片 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

完成上傳 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

取消上傳 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

上傳檔案

上傳圖片併傳送訊息

為使用者設定頭像

建立上傳

路徑引數

請求體

請求示例

響應

錯誤

上傳檔案內容

索取分片上傳地址

路徑引數

請求體

請求示例

響應

錯誤

查詢已上傳的分片

路徑引數

請求示例

響應

錯誤

完成上傳

路徑引數

請求示例

響應

錯誤

取消上傳

路徑引數

請求示例

響應

錯誤