Multimodal Understanding

Use MOSS-VL to understand images or video and return text in a Responses API object. Every request must include a text instruction and media: either 1–5 images or 1 video. Images and video cannot be mixed.

POST

/v1/responses

A synchronous multimodal understanding endpoint. Pass images or video by URL or file_id; the current output is text.

Authentication

Add Authorization: Bearer <API_KEY> to the request headers. Create API keys on the API Keys page in the console.

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

Supported model

Field	Allowed value
model	`moss-vl-1.0`

Input combinations

Scenario	content parts	Quantity
Single-image understanding	`input_text` + `input_image`	1 image
Multi-image understanding	`input_text` + multiple `input_image` parts	Up to 5 images
Video understanding	`input_text` + `input_video`	1 video

Request fields

Field	Type	Required	Description
model	string	Yes	The model ID. Multimodal understanding uses `moss-vl-1.0`; use `moss-vl-1.0-2026-07-08` when you need to pin a version.
input	array	Yes	The input message array. It must currently contain exactly one message with `role=user`.
input[].role	string	Yes	Currently fixed to `user`.
input[].content	array	Yes	The content array. It must include at least one non-empty `input_text` part and one valid set of media parts.
input[].content[].type	string	Yes	The content type: `input_text`, `input_image`, or `input_video`.
input_text.text	string	Yes	The image or video understanding instruction. It must be a non-empty string.
input_image.image_url	string	Conditional	An image URL reachable by the service; mutually exclusive with `file_id` in the same content item.
input_image.file_id	string	Conditional	The ID of an uploaded image; mutually exclusive with `image_url` in the same content item. Obtain it through Upload File.
input_video.video_url	string	Conditional	A video URL reachable by the service; mutually exclusive with `file_id` in the same content item.
input_video.file_id	string	Conditional	The ID of an uploaded video; mutually exclusive with `video_url` in the same content item. Obtain it through Upload File.
max_output_tokens	integer	No	The maximum number of output tokens, from 1 to 8192.

Request examples

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", "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",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Compare the similarities and differences between these images." },
          { "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",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Summarize the events in this video in chronological order." },
          { "type": "input_video", "video_url": "https://example.com/video.mp4" }
        ]
      }
    ],
    "max_output_tokens": 1024
  }'

Media input methods

Method	Field	Description
Publicly accessible URL	`image_url` / `video_url`	Use a public or signed URL reachable by the service; its signature must remain valid for the full request
File ID	`file_id`	Use Upload File first, then reference its `file_id` in an image or video content item

Use a URL or file_id to provide media. Each media content item must contain either its URL field or file_id, never both.

Usage limits

Item	Limit
Image count	1–5 per request
Video count	1 per request
Mixed image and video input	Not supported
Image size	Up to 30 MB per image
Video size	Up to 200 MB per video

Supported image formats: PNG, JPG, JPEG, WebP, BMP, GIF, and TIFF.

Supported video formats: MP4, M4V, AVI, MOV, WebM, and MKV.

Response fields

The endpoint returns a standard Responses API object. The table below lists the core fields needed to read the current text result; generated text is available at output[].content[].text.

Field	Type	Returned	Description
id	string	Yes	The Response ID, prefixed with `resp_`.
object	string	Yes	Always `response`.
created_at	integer	Yes	The creation time as a Unix timestamp in seconds.
status	string	Yes	The response status, currently `completed` or `incomplete`.
completed_at	integer	Yes	The terminal time as a Unix timestamp in seconds.
error	object \| null	Yes	`null` for successful or incomplete output. Failed requests use the platform synchronous error structure.
incomplete_details	object \| null	Yes	`null` for complete output. When the output limit is reached, it contains `reason=max_output_tokens`.
model	string	Yes	The model ID used for the request, currently `moss-vl-1.0`.
output	array	Yes	The output item list. It currently contains one assistant message.
output[].id	string	Yes	The message ID, prefixed with `msg_`.
output[].type	string	Yes	Always `message`.
output[].status	string	Yes	Matches the response status: `completed` or `incomplete`.
output[].role	string	Yes	Always `assistant`.
output[].content	array	Yes	The message content list. It currently contains one text output item.
output[].content[].type	string	Yes	Always `output_text`.
output[].content[].text	string	Yes	The text generated by the model.
usage.input_tokens	integer	Yes	The input token count.
usage.output_tokens	integer	Yes	The output token count.
usage.total_tokens	integer	Yes	The total input and output token count.

The actual response may also contain standard Responses API compatibility fields. Clients should read the fields they need and ignore unused additional fields. usage only reports usage returned by the endpoint; this page does not promise pricing, free quotas, or billing behavior.

Response example

{
  "id": "resp_task_abc123",
  "object": "response",
  "created_at": 1710000000,
  "status": "completed",
  "completed_at": 1710000001,
  "error": null,
  "incomplete_details": null,
  "model": "moss-vl-1.0",
  "output": [
    {
      "id": "msg_task_abc123",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "There are four nuts in the image."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 8743,
    "output_tokens": 94,
    "total_tokens": 8837
  }
}

Errors

The endpoint returns HTTP 400 before task creation for an invalid request structure, missing text or media, excessive media count, mixed image and video input, a media item containing both a URL and file_id, or max_output_tokens outside its allowed range.

The error body follows the platform synchronous error structure. Do not depend on unpublished media-specific error codes. Unavailable models, invalid URLs, service failures, and inference failures also follow the platform error contract.

Next steps

Upload File

Upload an image or video and obtain a reusable file_id.

Request Limits

Review the stable public API input limits.