图片与视频理解

使用 MOSS-VL 理解图片或视频，并以 Responses API 对象返回文本结果。每次请求必须同时包含文本指令和媒体。

场景信息

适用场景

• 单图内容理解
• 多图对比与总结
• 图片 OCR 与文档内容理解
• 视频摘要、事件理解与问答

调用步骤

1. 创建 API Key

   进入开发中心创建 API Key，并保存为环境变量。不要写进客户端代码或提交到仓库。

   MOSS_API_KEY="<your_api_key_here>"
   

2. 准备请求输入

   准备一条文本指令，并选择图片或视频的 file_id。本地图片或视频可先通过上传文件接口获取 file_id；同一次请求不能混合传入图片和视频。

   {
     "model": "moss-vl-1.0-2026-07-08",
     "input": [
       {
         "role": "user",
         "content": [
           { "type": "input_text", "text": "请描述图片中的主要内容。" },
           { "type": "input_image", "file_id": "<image_file_id>" }
         ]
       }
     ],
     "max_output_tokens": 1024
   }
   

   {
     "model": "moss-vl-1.0-2026-07-08",
     "input": [
       {
         "role": "user",
         "content": [
           { "type": "input_text", "text": "请按时间顺序总结视频中的事件。" },
           { "type": "input_video", "file_id": "<video_file_id>" }
         ]
       }
     ],
     "max_output_tokens": 1024
   }
   

3. 发起第一次请求

   向 /v1/responses 发起 JSON 请求。接口同步返回 Responses API 对象，当前输出为文本。

   如果使用图片理解示例，可将第 2 步的图片请求体保存为 request.json 后发起请求。

   curl https://api.mosi.cn/v1/responses \
     -H "Authorization: Bearer $MOSS_API_KEY" \
     -H "Content-Type: application/json" \
     -d @request.json
   

   import json
   import os
   import requests
   
   payload = json.load(open("request.json"))
   resp = requests.post(
       "https://api.mosi.cn/v1/responses",
       headers={"Authorization": f"Bearer {os.environ['MOSS_API_KEY']}"},
       json=payload,
   )
   print(resp.status_code)
   print(resp.json())
   

   const payload = {
     model: 'moss-vl-1.0-2026-07-08',
     input: [
       {
         role: 'user',
         content: [
           { type: 'input_text', text: '请描述图片中的主要内容。' },
           { type: 'input_image', file_id: '<image_file_id>' },
         ],
       },
     ],
     max_output_tokens: 1024,
   }
   
   const resp = await fetch('https://api.mosi.cn/v1/responses', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${apiKey}`,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify(payload),
   })
   
   console.log(resp.status)
   console.log(await resp.json())
   

4. 读取响应结果

   请求完成后读取 output[].content[].text。如果返回 status=incomplete，说明输出可能被 max_output_tokens 截断。

   {
     "status": "completed",
     "output": [
       {
         "type": "message",
         "role": "assistant",
         "content": [
           {
             "type": "output_text",
             "text": "图片中有四颗坚果。"
           }
         ]
       }
     ]
   }
   

5. 验证成功

   成功标准：响应状态为 completed，且 output[].content[].text 中包含模型生成的文本结果。

注意事项

• 当前单次最多 5 张图片或 1 个视频。
• 当前不支持图片和视频在同一次请求中混合输入。
• 场景指南主示例推荐使用 file_id，调用链路更稳定。
• 也可以通过 image_url / video_url 传入公网 URL 或对象存储 URL，但 URL 必须可由服务端访问；如果不确定 URL 是否稳定，建议先上传文件并使用 file_id。

下一步