下载与管理文件

本页介绍你的服务端如何下载本应用的文件、查询和删除文件、查看群文件列表和应用的存储用量。文件的用途、地址和保留规则见文件概述，上传见上传文件。

你的服务端可以下载本应用的全部消息附件和群文件，不需要以某个用户的身份，也不检查群成员身份。例如审核用户发送的图片、把群文件同步到你的业务系统。头像的公开地址可以直接访问，不需要换取。

换取下载地址

用文件地址或缩略图地址换取下载地址，一次最多 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&response-content-type=image%2Fjpeg&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）与应用套餐的存储容量中较小的一个
`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 }
  }
}

下载与管理文件 ​

换取下载地址 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

查询文件 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

删除文件 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

查询群文件列表 ​

路径参数 ​

查询参数 ​

请求示例 ​

响应 ​

错误 ​

查询存储用量 ​

路径参数 ​

请求示例 ​

响应 ​

下载与管理文件

换取下载地址

路径参数

请求体

请求示例

响应

错误

查询文件

路径参数

请求示例

响应

错误

删除文件

路径参数

请求示例

响应

错误

查询群文件列表

路径参数

查询参数

请求示例

响应

错误

查询存储用量

路径参数

请求示例

响应