多模态理解

使用 MOSS-VL 理解图片或视频，并以 Responses API 对象返回文本结果。每次请求必须同时包含文本指令和媒体；媒体可为 1～5 张图片或 1 个视频，图片与视频不能混合输入。

POST

/v1/responses

同步多模态理解接口。支持通过 URL 或 file_id 传入图片、视频，当前输出为文本。

认证

在请求头中加入 Authorization: Bearer <API_KEY> 完成鉴权，密钥可在控制台「API 密钥」页生成。

curl -X POST https://api.mosi.cn/v1/responses \
  -H "Authorization: Bearer $MOSS_API_KEY"

支持模型

字段	允许值
model	`moss-vl-1.0-2026-07-08`

输入组合

场景	content 组成	数量
单图理解	`input_text` + `input_image`	1 张图片
多图理解	`input_text` + 多个 `input_image`	最多 5 张图片
视频理解	`input_text` + `input_video`	1 个视频

请求字段

字段	类型	必填	说明
model	string	是	模型 ID，当前填写 `moss-vl-1.0-2026-07-08`。
input	array	是	输入消息数组；当前必须且只能包含一条 `role=user` 消息。
input[].role	string	是	当前固定为 `user`。
input[].content	array	是	内容数组；必须同时包含至少一个非空 `input_text` 和一组有效媒体。
input[].content[].type	string	是	内容类型：`input_text`、`input_image` 或 `input_video`。
input_text.text	string	是	图片或视频理解指令，必须为非空字符串。
input_image.image_url	string	条件必填	可由服务端访问的图片 URL；与同一内容项的 `file_id` 二选一。
input_image.file_id	string	条件必填	已上传图片的文件 ID；与同一内容项的 `image_url` 二选一。可通过上传文件获取。
input_video.video_url	string	条件必填	可由服务端访问的视频 URL；与同一内容项的 `file_id` 二选一。
input_video.file_id	string	条件必填	已上传视频的文件 ID；与同一内容项的 `video_url` 二选一。可通过上传文件获取。
max_output_tokens	integer	否	最大输出 Token 数，范围为 1～8192。

请求示例

curl https://api.mosi.cn/v1/responses \
  -H "Authorization: Bearer $MOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moss-vl-1.0-2026-07-08",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "请描述图片中的主要内容。" },
          { "type": "input_image", "image_url": "https://example.com/image.jpg" }
        ]
      }
    ],
    "max_output_tokens": 1024
  }'

curl https://api.mosi.cn/v1/responses \
  -H "Authorization: Bearer $MOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moss-vl-1.0-2026-07-08",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "请比较两张图片的异同。" },
          { "type": "input_image", "file_id": "<image_file_id_1>" },
          { "type": "input_image", "file_id": "<image_file_id_2>" }
        ]
      }
    ],
    "max_output_tokens": 1024
  }'

curl https://api.mosi.cn/v1/responses \
  -H "Authorization: Bearer $MOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moss-vl-1.0-2026-07-08",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "请按时间顺序总结视频中的事件。" },
          { "type": "input_video", "video_url": "https://example.com/video.mp4" }
        ]
      }
    ],
    "max_output_tokens": 1024
  }'

媒体传入方式

方式	字段	说明
公网可访问 URL	`image_url` / `video_url`	支持公开 URL 或签名 URL；URL 必须可由服务端访问，签名有效期需覆盖请求处理时间
File ID	`file_id`	先通过上传文件获取 `file_id`，再在图片或视频内容项中引用

建议通过 URL 或 file_id 传入媒体。每个媒体内容项只能填写对应的 URL 字段或 file_id，不能同时填写。

使用限制

项目	限制
图片数量	每次 1～5 张
视频数量	每次 1 个
图视频混输	不支持
单张图片大小	最大 30 MB
单个视频大小	最大 200 MB

支持的图片格式： PNG、JPG、JPEG、WebP、BMP、GIF、TIFF。

支持的视频格式： MP4、M4V、AVI、MOV、WebM、MKV。

响应字段

接口返回标准 Responses API 对象。下面列出读取当前文本结果所需的核心字段；生成文本位于 output[].content[].text。

字段	类型	必返	说明
id	string	是	Response ID，以 `resp_` 开头。
object	string	是	固定为 `response`。
created_at	integer	是	创建时间，Unix 时间戳，单位为秒。
status	string	是	响应状态，当前为 `completed` 或 `incomplete`。
completed_at	integer	是	请求进入终态的时间，Unix 时间戳，单位为秒。
error	object \| null	是	成功或输出不完整时为 `null`；请求失败使用平台同步错误结构返回。
incomplete_details	object \| null	是	输出完整时为 `null`；达到输出上限时包含 `reason=max_output_tokens`。
model	string	是	本次调用的模型 ID，当前为 `moss-vl-1.0-2026-07-08`。
output	array	是	输出项列表；当前包含一个 assistant message。
output[].id	string	是	消息 ID，以 `msg_` 开头。
output[].type	string	是	固定为 `message`。
output[].status	string	是	与响应状态一致，为 `completed` 或 `incomplete`。
output[].role	string	是	固定为 `assistant`。
output[].content	array	是	消息内容列表；当前包含一个文本输出项。
output[].content[].type	string	是	固定为 `output_text`。
output[].content[].text	string	是	模型生成的文本结果。
usage.input_tokens	integer	是	输入 Token 数。
usage.output_tokens	integer	是	输出 Token 数。
usage.total_tokens	integer	是	输入与输出 Token 总数。

实际响应还可能包含标准 Responses API 的兼容字段。客户端应读取需要的字段，并忽略未使用的附加字段。usage 仅表示接口响应中的用量信息，本页不承诺价格、免费额度或计费规则。

响应示例

{
  "id": "resp_task_abc123",
  "object": "response",
  "created_at": 1710000000,
  "status": "completed",
  "completed_at": 1710000001,
  "error": null,
  "incomplete_details": null,
  "model": "moss-vl-1.0-2026-07-08",
  "output": [
    {
      "id": "msg_task_abc123",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "图片中有四颗坚果。"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 8743,
    "output_tokens": 94,
    "total_tokens": 8837
  }
}

错误

以下情况在任务创建前返回 HTTP 400：请求结构错误、缺少文本或媒体、媒体数量超限、图片与视频混输、同一媒体项同时传 URL 与 file_id，以及 max_output_tokens 超出范围。

错误体沿用平台同步错误结构，不要依赖未公开的媒体专用错误码。模型不可用、URL 不合法、服务不可用和推理失败也按平台通用错误契约返回。

下一步

上传文件

上传图片或视频并获取可复用的 file_id。

请求限制

查看公开 API 的稳定输入限制。