画像・動画の理解

MOSS-VLで画像または動画を理解し、テキストの結果をResponses APIオブジェクトとして返します。各リクエストには、テキストの指示とメディアの両方を含める必要があります。

1. APIキーを作成

   APIキー管理プラットフォームでAPIキーを作成し、環境変数として保存してください。クライアントコードに書き込んだり、リポジトリにコミットしたりしないでください。

   MOSS_API_KEY=<your_api_key_here>

2. リクエスト入力を準備

   空でないテキストの指示を1つ用意し、画像または動画のfile_id、またはサーバー側からアクセスできる公開URL/署名付きURLを選択します。同じリクエストで画像と動画を混在させて渡すことはできません。

   フィールド型必須説明

   model: string必須

   moss-vl-1.0。スナップショットを固定する場合は、moss-vl-1.0-2026-07-08を使用できます

   input: array必須

   userメッセージを1件含める必要があり、その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任意

   最大出力トークン数を制御します

   {
     "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リクエストを送信します。APIは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": "画像には4つのナッツがあります。"
           }
         ]
       }
     ]
   }

5. 成功を確認

   成功の基準：レスポンスのステータスがcompletedであり、output[].content[].textにモデルが生成したテキストの結果が含まれています。

次のステップ