上传聊天资源

上传图片、语音、视频或文件，获得发送消息所需的 media。

POST /app/sdk/media/upload

调用方： SDK 客户端　·　认证： IM Token

请求头：Authorization: Bearer <IM Token>。先通过宿主后端获取 Token，再交给 SDK 使用。

上传方式：multipart/form-data。使用 curl 的 -F 时会自动设置包含 boundary 的 Content-Type，无需手写此请求头。

请求参数

Form

参数	类型	必填	说明
type	string	是	资源类型：image 图片、voice 语音、video 视频、file 文件。

Form 文件

参数	类型	必填	说明
file	file	是	要上传的本地文件。

请求示例

curl 'https://example.com/app/sdk/media/upload' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  -F 'type=image' \
  -F 'file=@/path/to/sunset.jpg'

使用说明

• 上传只是保存资源，不会自动发送消息。接着调用发送消息接口，提交对应 type 和完整 media。不要改写 URL、尺寸、MIME、时长或大小。
• 实际限制以读取首页数据接口返回的 media_limits 为准；服务器还会检查文件内容，不只看扩展名。
• 图片支持 JPEG、PNG、WebP、GIF，默认最大 8 MiB。源图单边最多 8000 像素，总像素最多 1600 万；静态展示图最长边 1920 像素，缩略图最长边 720 像素。
• 语音支持 M4A/AAC，或 16 kHz 单声道 16-bit PCM WAV；默认最大 10 MiB、60 秒，至少 1000 毫秒。
• 视频使用 MP4，包含 H.264 视频轨道，可带 AAC 音轨，默认最大 8 MiB。普通文件默认最大 8 MiB，可为空文件。

返回参数

成功响应的最外层字段如下。下面所有业务字段都位于 data 中。

字段	类型	说明
code	integer	0 表示成功；非 0 时查看 msg，不把 data 当成功结果使用。
msg	string	成功通常为 ok，失败时为错误说明。
data	object	本次请求的业务结果，字段见下表。

data 字段

字段	类型	说明
media	Media	服务器识别并处理后的资源信息。

返回示例

示例展示字段结构；ID、时间和资料仅作说明，请使用实际回包。

{
  "code": 0,
  "msg": "ok",
  "data": {
    "media": {
      "url": "https://example.com/uploads/resources/2026/10/ab590ea121b24453bf932153ad276ef5.webp",
      "thumbnail_url": "https://example.com/uploads/resources/2026/10/c132a69a9c87430abf9df99e59988e12.webp",
      "mime_type": "image/webp",
      "file_name": "coast-sunset.jpg",
      "size": 186240,
      "width": 1080,
      "height": 1920,
      "duration_ms": null
    }
  }
}

返回对象字段

数组中的每个对象使用同一套字段。点击名称跳到说明：

媒体资源

媒体资源（Media）

字段	类型	说明
url	string	原资源地址。发送媒体消息时原样使用上传接口给出的地址。
thumbnail_url	string | null	图片缩略图或视频封面地址；没有缩略图时为 null。
mime_type	string	资源的 MIME 类型，例如 image/webp。
file_name	string | null	原文件名称；不适用时为 null。
size	integer	资源大小，单位为字节。
width	integer | null	图片或视频宽度，单位为像素；不适用或未提供时为 null。
height	integer | null	图片或视频高度，单位为像素；不适用或未提供时为 null。
duration_ms	integer | null	媒体时长，单位为毫秒；不适用或尚未解析时为 null。当前视频上传结果的此项为 null。

错误处理

先检查 HTTP 状态，再检查 code。业务失败可能仍为 HTTP 200；非 0 的 code 都不能当成功。完整错误码见请求约定。

返回上传与下载接口列表 · HTTP 请求约定