下載與管理檔案

從你的服務端下載、查詢和刪除本應用的檔案。你的服務端可以下載全部訊息附件和群檔案，不需要以某個使用者的身份，也不檢查群成員身份，例如稽核使用者發的圖片、把群檔案同步到你的系統。頭像的公開地址可以直接訪問，不用換取。

要做什麼	介面
下載訊息附件、群檔案	換取下載地址，再直接 `GET` 下載地址
確認上傳狀態，檢視遮蔽、刪除原因	查詢檔案
撤回後連附件一起刪掉	刪除檔案
列出一個群的群檔案	查詢群檔案列表
看應用用了多少儲存	查詢儲存用量

例如，下載一張圖片附件：

bash

DL=$(curl -s -X POST "$IM_API/$ORG/$APP/media/download-urls" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://im.example.com/media/v1/f/99606017553203200/5nOzK6E40hgYIKl80dYVLQ"] }' \
  | jq -r '.items[0].download_url')
curl -o photo.jpg "$DL"   # 不要带 Authorization 请求头

檔案的用途、地址和保留規則見檔案概述，上傳見上傳檔案。

換取下載地址

用檔案地址或縮圖地址換取下載地址，一次最多 100 個。每個地址分別給出結果，某個地址失敗不影響其他地址；整個請求只計一次 OpenAPI 呼叫。

怎麼下載：直接 GET 下載地址，不需要也不能帶 Authorization 請求頭，支援 Range（斷點續傳）。
有效期 60 到 90 分鐘：簽名時刻按 30 分鐘對齊、有效 90 分鐘，同一個檔案在同一個 30 分鐘內換到的地址相同，可以按地址快取。不要儲存下載地址或寫進訊息，到期後重新換取。
響應頭：Content-Type 為識別出的格式；file 型別的檔案和全部群檔案另帶 Content-Disposition: attachment 和上傳時的檔名（RFC 6266 的 filename* 編碼），瀏覽器會下載而不是開啟。縮圖地址換到的是縮圖的下載地址，不帶 Content-Disposition。

POST/{org_name}/{app_name}/media/download-urls

路徑引數

org_name、app_name 見接入概述。

請求體

欄位	型別	必填	說明
`urls`	Array<String>	是	檔案地址或縮圖地址，1 到 100 個，可以重複。必須與介面返回的地址完全相同，不能帶查詢引數

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/media/download-urls" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://im.example.com/media/v1/f/99606093402996736/DC0neNm6HBbxGW9bN6g_iA",
      "https://im.example.com/media/v1/f/99606093402996736/DC0neNm6HBbxGW9bN6g_iA/thumb",
      "https://im.example.com/media/v1/f/99607013226446848/qVIBwfZmwXMrh_FiZMqI-Q",
      "https://example.com/a.jpg"
    ]
  }'

響應

成功返回 200 OK。即使全部地址都失敗，也返回 200，請檢查每一項：

欄位	型別	說明
`items`	Array<Object>	每個地址的結果，與請求中的 `urls` 一一對應、順序相同
`items[].url`	String	請求中的地址
`items[].download_url`	String	下載地址。只在成功時出現
`items[].expires_at`	String	下載地址的到期時間，距現在 60 到 90 分鐘。只在成功時出現
`items[].code`	String	錯誤碼，見下表。只在失敗時出現
`items[].message`	String	錯誤說明。只在失敗時出現

失敗的項的 code：

`code`	說明
`not_found`	不是本服務的檔案地址，如頭像的公開地址、帶了查詢引數的地址（“不是本服務的檔案地址”）；檔案不存在、不屬於本應用、金鑰不對、還在上傳中，或者對不是圖片的檔案請求了縮圖（“檔案不存在”）；檔案刪除超過約 30 天
`file_expired`	檔案已過期或已被刪除
`file_blocked`	檔案因違規已被遮蔽，遮蔽可能來自內容安全或平臺，見違規檔案的遮蔽

json

{
  "items": [
    {
      "url": "https://im.example.com/media/v1/f/99606093402996736/DC0neNm6HBbxGW9bN6g_iA",
      "download_url": "https://storage.example.com/im-private/t99604914749046784/a99604957103128576/m/99606093402996736?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Date=20261002T203000Z&X-Amz-Expires=5400&X-Amz-SignedHeaders=host&X-Amz-Signature=468e6e29...",
      "expires_at": "2026-10-02T22:00:00.000Z"
    },
    {
      "url": "https://im.example.com/media/v1/f/99606093402996736/DC0neNm6HBbxGW9bN6g_iA/thumb",
      "download_url": "https://storage.example.com/im-private/t99604914749046784/a99604957103128576/m/99606093402996736_thumb?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Date=20261002T203000Z&X-Amz-Expires=5400&X-Amz-SignedHeaders=host&X-Amz-Signature=52ca87a0...",
      "expires_at": "2026-10-02T22:00:00.000Z"
    },
    {
      "url": "https://im.example.com/media/v1/f/99607013226446848/qVIBwfZmwXMrh_FiZMqI-Q",
      "code": "file_expired",
      "message": "文件已过期或已被删除"
    },
    {
      "url": "https://example.com/a.jpg",
      "code": "not_found",
      "message": "不是本服务的文件地址"
    }
  ]
}

下載地址是物件儲存或 CDN 的地址，形式取決於服務的部署，請原樣使用，不要解析或修改其中的引數。

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`urls` 為空或超過 100 個

查詢檔案

按檔案 ID 查詢一個檔案的資訊，包括上傳中、已遮蔽和已刪除的檔案（刪除的記錄保留約 30 天），可以用來確認上傳狀態、檢視遮蔽原因和刪除原因。檔案 ID 是檔案地址中 /media/v1/f/ 之後的第一段。

GET/{org_name}/{app_name}/media/files/{file_id}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`file_id`	String	檔案 ID

請求示例

bash

curl "$IM_API/$ORG/$APP/media/files/99606563727081472" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，響應體為檔案物件。一個群檔案：

json

{
  "file_id": "99606563727081472",
  "purpose": "group_file",
  "kind": "file",
  "status": "active",
  "url": "https://im.example.com/media/v1/f/99606563727081472/irgzYRVvGPU86eyqPiJ8RQ",
  "thumbnail_url": null,
  "name": "Q3 需求评审.pdf",
  "content_type": "application/pdf",
  "size": 3145728,
  "width": null,
  "height": null,
  "owner": "bob",
  "group_id": "99606031272771584",
  "via": "openapi",
  "created_at": "2026-10-02T20:40:55.393Z",
  "expires_at": null,
  "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
}

一個已被刪除的圖片附件：

json

{
  "file_id": "99607013226446848",
  "purpose": "attachment",
  "kind": "image",
  "status": "deleted",
  "url": "https://im.example.com/media/v1/f/99607013226446848/qVIBwfZmwXMrh_FiZMqI-Q",
  "thumbnail_url": null,
  "name": null,
  "content_type": "image/png",
  "size": 1142,
  "width": 200,
  "height": 200,
  "owner": null,
  "group_id": null,
  "via": "openapi",
  "created_at": "2026-10-02T20:42:42.563Z",
  "expires_at": "2026-11-01T20:42:42.563Z",
  "in_use": false,
  "sha256": "199a0ebb10df2101addbe8e3e39dea251149353f7f779245c3e337acfdc4f50c",
  "created_by": "99604957107322880",
  "blocked_at": null,
  "blocked_by": null,
  "block_rule_source": null,
  "block_reason": null,
  "deleted_at": "2026-10-02T20:42:42.838Z",
  "delete_reason": "deleted"
}

錯誤

HTTP 狀態碼	`code`	說明
404	`not_found`	檔案不存在、不屬於本應用，或刪除已超過約 30 天

刪除檔案

刪除本應用的一個檔案：訊息附件、使用者頭像、群頭像或群檔案，包括客戶端上傳的。刪除不可撤銷，刪除後：

方面	結果
下載	立即不能換取下載地址，得到 `file_expired`，客戶端顯示“檔案已過期”
引用它的訊息	不變：訊息仍在，`body` 中的地址不變，只是不能下載
正在使用的頭像	資料不會自動修改，資料中的頭像隨後無法訪問，請同時修改資料
群檔案	從群檔案列表移除
儲存	用量隨即減少；內容約 10 分鐘後從儲存刪除，在此之前已換取的下載地址可能仍可用；頭像公開地址的 CDN 快取最長 1 天后失效

撤回訊息不會刪除訊息中的附件：同一個檔案地址可能已被轉發到其他會話中。你的業務需要“撤回即刪除”時，可以在撤回之後從附件的地址中取出檔案 ID，呼叫本介面刪除。

重複刪除已刪除的檔案返回成功。被遮蔽的檔案不能刪除。還在上傳中的檔案不能用本介面刪除，請取消上傳。

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

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`file_id`	String	檔案 ID

請求示例

bash

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

響應

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

錯誤

HTTP 狀態碼	`code`	說明
403	`file_blocked`	檔案因違規已被遮蔽（由內容安全或平臺遮蔽），不能刪除。按平臺規則遮蔽的檔案你不能解除，見違規檔案的遮蔽
404	`not_found`	檔案不存在、不屬於本應用，或者還在上傳中

查詢群檔案列表

查詢一個群中可用的群檔案，按上傳時間從新到舊排列，同時返回全群的檔案數和佔用的空間。只列出狀態為 active 的檔案，不能按型別、上傳者等條件篩選，也不能改變排序。服務端查詢不檢查成員身份；群被封禁時照常列出。

GET/{org_name}/{app_name}/media/groups/{group_id}/files

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`group_id`	String	群 ID

查詢引數

引數	型別	必填	說明
`limit`	Number	否	每頁的檔案數，預設 20，取值 1 到 100
`cursor`	String	否	上一頁返回的 `next_cursor`，第一頁不傳，見分頁

請求示例

bash

curl "$IM_API/$ORG/$APP/media/groups/99606031272771584/files?limit=20" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
`file_count`	Number	全群可用的群檔案數，每個群最多 1000 個
`used_bytes`	Number	全群的群檔案佔用的空間，位元組，圖片包括縮圖
`items`	Array<Object>	本頁的群檔案，每項為檔案物件，`owner` 為上傳者（客戶端上傳的）或上傳時指定的使用者
`next_cursor`	String	下一頁的遊標，為 `null` 時表示沒有下一頁

json

{
  "file_count": 2,
  "used_bytes": 3146870,
  "items": [
    {
      "file_id": "99606564578525184",
      "purpose": "group_file",
      "kind": "image",
      "status": "active",
      "url": "https://im.example.com/media/v1/f/99606564578525184/d-3evFyEZ9u3Q4YGEFMGDg",
      "thumbnail_url": "https://im.example.com/media/v1/f/99606564578525184/d-3evFyEZ9u3Q4YGEFMGDg/thumb",
      "name": "示意图.png",
      "content_type": "image/png",
      "size": 1142,
      "width": 200,
      "height": 200,
      "owner": null,
      "group_id": "99606031272771584",
      "via": "openapi",
      "created_at": "2026-10-02T20:40:55.596Z",
      "expires_at": null,
      "in_use": false,
      "sha256": "199a0ebb10df2101addbe8e3e39dea251149353f7f779245c3e337acfdc4f50c",
      "created_by": "99604957107322880",
      "blocked_at": null,
      "blocked_by": null,
      "block_rule_source": null,
      "block_reason": null,
      "deleted_at": null,
      "delete_reason": null
    },
    {
      "file_id": "99606563727081472",
      "purpose": "group_file",
      "kind": "file",
      "status": "active",
      "url": "https://im.example.com/media/v1/f/99606563727081472/irgzYRVvGPU86eyqPiJ8RQ",
      "thumbnail_url": null,
      "name": "Q3 需求评审.pdf",
      "content_type": "application/pdf",
      "size": 3145728,
      "width": null,
      "height": null,
      "owner": "bob",
      "group_id": "99606031272771584",
      "via": "openapi",
      "created_at": "2026-10-02T20:40:55.393Z",
      "expires_at": null,
      "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
    }
  ],
  "next_cursor": null
}

群解散後，群檔案隨即由後臺刪除，通常 1 分鐘內列表變為空；之後向這個群上傳群檔案返回 404 not_found。

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`limit` 不在 1 到 100 之間，或 `cursor` 無效
404	`not_found`	群不存在（“群不存在或已解散”）。已解散的群照常返回，列出還沒有刪除的群檔案

查詢儲存用量

查詢應用當前的儲存用量和額度，按用途分別列出。用量統計可用的檔案（status 為 active），圖片包括縮圖，上傳中、已刪除和被遮蔽的檔案不計入；檔案完成上傳、刪除、被遮蔽時即時更新。額度見儲存用量與額度。

GET/{org_name}/{app_name}/media/usage

路徑引數

org_name、app_name 見接入概述。

請求示例

bash

curl "$IM_API/$ORG/$APP/media/usage" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
`used_bytes`	Number	已用的空間，位元組
`file_count`	Number	可用的檔案數
`limit_bytes`	Number	應用的儲存額度，位元組：開啟檔案儲存額度限制時為平臺的儲存配額（預設 1099511627776，即 1024 GB）與應用套餐的儲存容量中較小的一個；關閉限制時為 `0`，表示不限
`by_purpose`	Object	按用途的用量，鍵為用途，每項有 `used_bytes` 和 `file_count`。總是列出全部用途，沒有檔案的為 0。`chatroom_avatar` 為聊天室封面

json

{
  "used_bytes": 37064934,
  "file_count": 9,
  "limit_bytes": 1099511627776,
  "by_purpose": {
    "attachment": { "used_bytes": 37043998, "file_count": 4 },
    "chatroom_avatar": { "used_bytes": 0, "file_count": 0 },
    "group_avatar": { "used_bytes": 2026, "file_count": 1 },
    "group_file": { "used_bytes": 1193, "file_count": 2 },
    "user_avatar": { "used_bytes": 17717, "file_count": 2 }
  }
}

下載相容性

下載地址不攜帶 response-content-type，以完成上傳時寫入物件的檔案型別為準，支援阿里雲 OSS。舊地址返回 HTTP 400 且錯誤為 Can not override response header on content-type（0017-00000902）時，請更新服務端並重新換取下載地址；簽名地址不能手動刪除引數。

下載與管理檔案 ​

換取下載地址 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

查詢檔案 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

刪除檔案 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

查詢群檔案列表 ​

路徑引數 ​

查詢引數 ​

請求示例 ​

響應 ​

錯誤 ​

查詢儲存用量 ​

路徑引數 ​

請求示例 ​

響應 ​

下載與管理檔案

換取下載地址

路徑引數

請求體

請求示例

響應

錯誤

查詢檔案

路徑引數

請求示例

響應

錯誤

刪除檔案

路徑引數

請求示例

響應

錯誤

查詢群檔案列表

路徑引數

查詢引數

請求示例

響應

錯誤

查詢儲存用量

路徑引數

請求示例

響應