上传视频及封面

把一段视频和对应封面一起上传。返回的 media 可用于发送视频消息。

POST /app/sdk/media/video

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

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

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

请求参数

Form 文件

参数	类型	必填	说明
file	file	是	MP4 视频文件，H.264 视频轨道，可选 AAC 音轨。
cover	file	是	视频封面，JPEG、PNG 或 WebP 静态图片。

请求示例

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

使用说明

• 只提交 file 和 cover 两个文件字段，不需要 type，也不接受其他普通文本字段。
• 上传只是保存资源，不会自动发送消息。接着调用发送消息接口，提交对应 type 和完整 media。不要改写 URL、尺寸、MIME、时长或大小。
• 实际限制以读取首页数据接口返回的 media_limits 为准；服务器还会检查文件内容，不只看扩展名。
• 图片支持 JPEG、PNG、WebP、GIF，默认最大 8 MiB。源图单边最多 8000 像素，总像素最多 1600 万；静态展示图最长边 1920 像素，缩略图最长边 720 像素。
• width 和 height 表示封面的展示尺寸；当前视频 duration_ms 返回 null，不要自行填入一个未经服务器确认的时长。

返回参数

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

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

data 字段

字段	类型	说明
media	Media	视频资源信息；thumbnail_url 为封面地址。

返回示例

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

{
  "code": 0,
  "msg": "ok",
  "data": {
    "media": {
      "url": "https://example.com/uploads/resources/2026/10/27fb97b192994d47a502ff969d146f6a.mp4",
      "thumbnail_url": "https://example.com/uploads/resources/2026/10/c132a69a9c87430abf9df99e59988e12.webp",
      "mime_type": "video/mp4",
      "file_name": "coast-sunset.mp4",
      "size": 2186240,
      "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 请求约定