图片与视频理解

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

1. 创建 API Key

   进入API Key 管理平台创建 API Key，并保存为环境变量。不要写进客户端代码或提交到仓库。

   MOSS_API_KEY=<your_api_key_here>

2. 准备请求输入

   准备一条非空文本指令，并选择图片或视频的 file_id，或服务端可访问的公网/签名 URL；同一次请求不能混合传入图片和视频。

   字段类型要求说明

   model: string必填

   moss-vl-1.0；如需锁定快照，可使用 moss-vl-1.0-2026-07-08

   input: array必填

   必须包含一条 user 消息，content 中同时包含 input_text 和有效媒体

   显示 6 个子字段

   input[].content: array必填

   内容数组，必须同时包含非空文本和有效媒体

   input[].content[].type: string必填

   可选值：input_text、input_image、input_video

   input[].content[].text: string条件必填

   type=input_text 时必填，且不能为空

   input[].content[].image_url: string条件必填

   图片 URL，与同一媒体项的 file_id 二选一

   input[].content[].video_url: string条件必填

   视频 URL，与同一媒体项的 file_id 二选一

   input[].content[].file_id: string条件必填

   已上传媒体的文件 ID，与对应的 URL 字段二选一

   max_output_tokens: integer可选

   控制最大输出 Token 数

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

3. 发起第一次请求

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

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

   import os
   import requests
   
   resp = requests.post(
       "https://api.mosi.cn/v1/responses",
       headers={
           "Authorization": f"Bearer {os.environ['MOSS_API_KEY']}",
           "Content-Type": "application/json",
       },
       json={
           "model": "moss-vl-1.0",
           "input": [
               {
                   "role": "user",
                   "content": [
                       {
                           "type": "input_text",
                           "text": "请描述图片中的主要内容。"
                       },
                       {
                           "type": "input_image",
                           "file_id": "<image_file_id>"
                       }
                   ]
               }
           ],
           "max_output_tokens": 1024
       },
   )
   
   print(resp.status_code)
   print(resp.json())

   const response = await fetch("https://api.mosi.cn/v1/responses", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.MOSS_API_KEY}`,
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
     "model": "moss-vl-1.0",
     "input": [
       {
         "role": "user",
         "content": [
           {
             "type": "input_text",
             "text": "请描述图片中的主要内容。"
           },
           {
             "type": "input_image",
             "file_id": "<image_file_id>"
           }
         ]
       }
     ],
     "max_output_tokens": 1024
   }),
   });
   
   console.log(response.status);
   console.log(await response.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 中包含模型生成的文本结果。

下一步