Image and Video Understanding

Use MOSS-VL to understand images or video and return text in a Responses API object. Every request must include both a text instruction and media.

1. Create an API Key

   Open the API Key Management Platform, create an API Key, and save it as an environment variable. Do not write it into client-side code or commit it to a repository.

   MOSS_API_KEY=<your_api_key_here>

2. Prepare the request input

   Prepare a non-empty text instruction and select an image or video file_id, or a public or signed URL accessible to the service. Images and videos cannot be mixed in one request.

   FieldTypeRequirementDescription

   model: stringRequired

   moss-vl-1.0; use moss-vl-1.0-2026-07-08 to pin a snapshot

   input: arrayRequired

   Must contain one user message whose content includes both input_text and valid media

   Show 6 child fields

   input[].content: arrayRequired

   Content array that must include both non-empty text and valid media

   input[].content[].type: stringRequired

   Allowed values: input_text, input_image, input_video

   input[].content[].text: stringConditionally required

   Required when type=input_text; must not be empty

   input[].content[].image_url: stringConditionally required

   Image URL; provide either this field or file_id for the same media item

   input[].content[].video_url: stringConditionally required

   Video URL; provide either this field or file_id for the same media item

   input[].content[].file_id: stringConditionally required

   File ID of uploaded media; provide either this field or the corresponding URL field

   max_output_tokens: integerOptional

   Controls the maximum number of output tokens

   {
     "model": "moss-vl-1.0",
     "input": [
       {
         "role": "user",
         "content": [
           { "type": "input_text", "text": "Describe the main content of this image." },
           { "type": "input_image", "file_id": "<image_file_id>" }
         ]
       }
     ],
     "max_output_tokens": 1024
   }

3. Send your first request

   Send a JSON request to /v1/responses. The endpoint synchronously returns a Responses API object with text output.

   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": "Describe the main content of this image." },
           { "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": "Describe the main content of this image."
                       },
                       {
                           "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": "Describe the main content of this image."
           },
           {
             "type": "input_image",
             "file_id": "<image_file_id>"
           }
         ]
       }
     ],
     "max_output_tokens": 1024
   }),
   });
   
   console.log(response.status);
   console.log(await response.json());

4. Read the response

   After the request completes, read output[].content[].text. If the response returns status=incomplete, the output may have been truncated by max_output_tokens.

   {
     "status": "completed",
     "output": [
       {
         "type": "message",
         "role": "assistant",
         "content": [
           {
             "type": "output_text",
             "text": "There are four nuts in the image."
           }
         ]
       }
     ]
   }

5. Verify success

   Success means the response status is completed and output[].content[].text contains text generated by the model.

Next steps