Vertex AI 400エラーの解決：roleパラメータの差異による3つのリクエストボディ形式の問題

Google Gemini API を使用する際、AI Studio から Vertex AI への移行は多くの開発者が通る道です。しかし、一見単純な role パラメータの違いが、数多くの開発者を悩ませています。

[&{Please use a valid role: user, model. (request id: xxx) 400 }]

この 400 エラーの根本的な原因は、Vertex AI では contents 配列内の各オブジェクトに role フィールドを含めることが強制されているのに対し、AI Studio ではシングルターム対話において省略可能であることにあります。

本記事では、Vertex AI と AI Studio のリクエストボディ形式の差異を深く掘り下げ、3つのシナリオにおける完全な解決策を提供します。

Vertex AI と AI Studio の主な差異の概要

400 エラーを解決する前に、まず両プラットフォームの決定的な違いを理解する必要があります。

プラットフォームの位置付けの差異

比較項目	AI Studio (Google AI)	Vertex AI
ターゲットユーザー	開発者の迅速なプロトタイプ検証	エンタープライズレベルの本番デプロイ
認証方法	API キー	サービスアカウント / OAuth
レート制限	基本的な制限、商用利用不可	本番環境レベルの制限、商用利用可能
role フィールド	シングルターム対話では省略可能	強制必須
エンドポイント形式	generativelanguage.googleapis.com	{region}-aiplatform.googleapis.com
利用可能プラットフォーム	APIYI apiyi.com, 公式 API	APIYI apiyi.com, Google Cloud

なぜ role 400 エラーが発生するのか

Vertex AI はエンタープライズレベルのプラットフォームとして、リクエスト形式の検証がより厳格です。リクエストボディに role フィールドが欠けていると、Vertex AI は即座に以下を返します。

{
  "error": {
    "code": 400,
    "message": "Please use a valid role: user, model.",
    "status": "INVALID_ARGUMENT"
  }
}

🎯 技術的なアドバイス: AI Studio から Vertex AI に移行する際は、APIYI apiyi.com プラットフォームを通じてインターフェース呼び出しのテストを行うことをお勧めします。このプラットフォームは統一された API インターフェース形式を提供し、異なるプラットフォーム間のパラメータの差異を自動的に処理するため、技術ソリューションの実現可能性を迅速に検証するのに役立ちます。

Vertex AI リクエストボディ形式の詳説

Vertex AI の正しいリクエスト形式

Vertex AI の Gemini API リクエストボディは、以下の構造に従う必要があります。

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "大規模言語モデルとは何かを説明してください"
        }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 2048
  }
}

role パラメータの有効値

Vertex AI が受け入れる role の値は以下の 2 つだけです。

role 値	意味	使用シーン
`user`	ユーザー入力	モデルに送信する質問または指示
`model`	モデルの応答	マルチターンの対話における履歴の返答

誤った例 vs 正しい例

❌ 誤り：role フィールドが不足（AI Studio スタイル）

{
  "contents": [
    {
      "parts": [
        {
          "text": "Hello, how are you?"
        }
      ]
    }
  ]
}

✅ 正しい：role フィールドが含まれている（Vertex AI スタイル）

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Hello, how are you?"
        }
      ]
    }
  ]
}

AI Studio リクエストボディ形式の詳説

AI Studio の寛容なモード

AI Studio (Google AI) はリクエスト形式の要件が比較的緩く、シングルターンの対話シーンにおいては role フィールドを省略できます。

{
  "contents": [
    {
      "parts": [
        {
          "text": "What is machine learning?"
        }
      ]
    }
  ]
}

2 つのプラットフォームのリクエストボディ比較

フィールド	AI Studio	Vertex AI
`contents`	必須	必須
`contents[].role`	任意 (シングルターン)	必須
`contents[].parts`	必須	必須
`contents[].parts[].text`	必須	必須
`systemInstruction`	対応	対応
`generationConfig`	任意	任意

マルチターンの対話シーン

マルチターンの対話では、両プラットフォームの形式は一致する傾向にあり、どちらも role を明示的に指定する必要があります。

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "こんにちは、自己紹介をしてください"}]
    },
    {
      "role": "model",
      "parts": [{"text": "こんにちは！私は Gemini です。Google が開発した AI アシスタントです..."}]
    },
    {
      "role": "user",
      "parts": [{"text": "何ができますか？"}]
    }
  ]
}

3つのシナリオに対応する完全な解決策

シナリオ 1：Python SDKによるVertex AIの呼び出し

Google公式のPython SDKを使用する場合、roleパラメータが正しく渡されていることを確認してください。

from google import genai
from google.genai.types import Content, Part

# 初始化客户端
client = genai.Client(
    vertexai=True,
    project="your-project-id",
    location="us-central1"
)

# 正确的请求格式 - 必须包含 role
contents = [
    Content(
        role="user",
        parts=[Part(text="什么是 Vertex AI?")]
    )
]

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=contents
)

print(response.text)

シナリオ 2：REST APIによる直接呼び出し

curlやHTTPクライアントを使用して、Vertex AI REST APIを直接呼び出します。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://us-central1-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT/locations/us-central1/publishers/google/models/gemini-2.0-flash:generateContent" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {"text": "解释量子计算的基本原理"}
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 1024
    }
  }'

💡 クイックスタート: プロトタイプを迅速に構築するには、APIYI（apiyi.com）プラットフォームの使用をお勧めします。このプラットフォームは、すぐに使えるAPIインターフェースを提供し、Vertex AIとAI Studioのフォーマットの違いを統一的に処理します。複雑な設定は不要で、5分で統合が完了します。

シナリオ 3：OpenAI互換形式での呼び出し

コードがOpenAI SDKに基づいている場合は、互換形式を使用できます。

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # 使用 APIYI 统一接口
)

# OpenAI 兼容格式自动处理 role
response = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[
        {"role": "user", "content": "什么是神经网络?"}
    ]
)

print(response.choices[0].message.content)

Vertex AI Express Modeの特殊なケース

Vertex AI Express Modeとは

Vertex AI Express Modeは、AI Studioと標準のVertex AIの中間に位置するオプションです。

特徴	AI Studio	Vertex AI Express	Vertex AI Standard
認証方法	API Key	API Key	Service Account
レート制限	基本	プロダクションレベル	プロダクションレベル
商用ライセンス	いいえ	はい	はい
roleの要件	任意	必須	必須
エンドポイント	generativelanguage	aiplatform	aiplatform

Express Modeのrole要件

Express ModeでAPIキー認証を使用する場合（AI Studioと同様）でも、Vertex AIの厳格なフォーマット要件を継承しているため、roleフィールドは必須です。

# Express Mode 示例 - role 必填
import requests

url = "https://us-central1-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT/locations/us-central1/publishers/google/models/gemini-2.0-flash:generateContent"

headers = {
    "Content-Type": "application/json",
    "X-Goog-Api-Key": "YOUR_API_KEY"
}

data = {
    "contents": [
        {
            "role": "user",  # 必须包含!
            "parts": [{"text": "Hello World"}]
        }
    ]
}

response = requests.post(url, headers=headers, json=data)

よくあるエラーのトラブルシューティングガイド

エラー 1: Please use a valid role: user, model

原因: contents 配列内のオブジェクトに role フィールドが欠けています。

解決策:

{
  "contents": [
    {
+     "role": "user",
      "parts": [{"text": "..."}]
    }
  ]
}

エラー 2: Invalid role value

原因: role フィールドに無効な値（"system"、"assistant" など）が使用されています。

解決策: Vertex AI は user と model のみを受け入れます。system や assistant は使用できません。

{
  "contents": [
    {
-     "role": "assistant",
+     "role": "model",
      "parts": [{"text": "..."}]
    }
  ]
}

エラー 3: System instructions の配置エラー

原因: システムプロンプトを systemInstruction フィールドではなく、contents 内に配置しています。

解決策:

{
  "systemInstruction": {
    "parts": [{"text": "あなたはプロの技術コンサルタントです"}]
  },
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "APIとは何か説明してください"}]
    }
  ]
}

💰 コスト最適化: API形式の頻繁なテストが必要なプロジェクトでは、APIYI（apiyi.com）プラットフォーム経由でのAPI呼び出しを検討してみてください。このプラットフォームは柔軟な料金体系とより手頃な価格を提供しており、中小規模のチームや個人開発者の開発デバッグに適しています。

移行チェックリスト

AI Studio から Vertex AI に移行する際は、以下のリストを使用してリクエスト形式が正しいか確認してください。

必須の修正項目

チェック項目	AI Studio での書き方	Vertex AI での書き方
role フィールド	省略可能	必須追加 `"role": "user"`
エンドポイント URL	generativelanguage.googleapis.com	{region}-aiplatform.googleapis.com
認証方式	`x-goog-api-key`	`Authorization: Bearer`
モデルパス	models/gemini-pro	publishers/google/models/gemini-pro

コード移行の例

移行前 (AI Studio):

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")
model = genai.GenerativeModel('gemini-pro')
response = model.generate_content("Hello")

移行後 (Vertex AI):

from google import genai
from google.genai.types import Content, Part

client = genai.Client(vertexai=True, project="your-project", location="us-central1")

contents = [
    Content(role="user", parts=[Part(text="Hello")])  # role は必須
]

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=contents
)

マルチモーダルリクエストの role 処理

画像 + テキストのリクエスト

画像を含むマルチモーダルリクエストを送信する場合も、同様に role を指定する必要があります。

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "描述这张图片的内容"},
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "BASE64_ENCODED_IMAGE"
          }
        }
      ]
    }
  ]
}

Cloud Storage ファイルの使用

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "分析这个视频的主要内容"},
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "gs://your-bucket/video.mp4"
          }
        }
      ]
    }
  ]
}

よくある質問 FAQ

Q1: なぜ AI Studio では role を省略できるのに、Vertex AI ではできないのですか？

AI Studio は迅速なプロトタイプ検証用ツールとして設計されているため、フォーマット要件が比較的緩やかです。一方、Vertex AI はエンタープライズ向けの製品プラットフォームであり、システムの安定性とメンテナンス性を確保するために厳格なリクエスト形式が求められます。APIYI（apiyi.com）プラットフォームを利用すれば、無料のテストクレジットを取得して、異なるプラットフォームのフォーマット要件を素早く検証できます。

Q2: Vertex AI は system role をサポートしていますか？

サポートしていません。Vertex AI の role は user と model の 2 つの値のみを受け入れます。システム指示が必要な場合は、別途 systemInstruction フィールドを使用してください：

{
  "systemInstruction": {
    "parts": [{"text": "あなたのシステムプロンプト"}]
  },
  "contents": [...]
}

Q3: OpenAI 形式の assistant はどのようにマッピングされますか？

OpenAI 形式の assistant role は、Vertex AI の model role に対応します。APIYI（apiyi.com）の統合インターフェースを使用している場合、このマッピングは自動的に処理されます。

Q4: リクエスト形式が正しいかどうかを素早くテストするにはどうすればよいですか？

以下の方法で素早く検証することをお勧めします：

APIYI プラットフォームでテストする: リクエスト形式のチェックとエラー表示機能が提供されています。
Google Cloud Console を使用する: Vertex AI Studio がビジュアルなテストインターフェースを提供しています。
ローカルで Mock テストを行う: まず AI Studio でロジックを検証し、その後フォーマットを修正して Vertex AI に移行します。

Q5: Vertex AI Express Mode と標準モードの形式は同じですか？

はい、両者のリクエストボディの形式は完全に同じで、いずれも role フィールドが必須です。主な違いは認証方法（API キーかサービスアカウントか）にあります。

まとめ

Vertex AI と AI Studio のリクエストボディ形式の主な違いは、role フィールドの必須要件にあります。

プラットフォーム	role の要件	有効な値
AI Studio	シングルターンは任意、マルチターンは必須	user, model
Vertex AI	常に必須	user, model
Vertex AI Express	常に必須	user, model

400 エラーを解決するための重要なステップ:

各 contents オブジェクトに "role": "user" または "role": "model" が含まれていることを確認する
システム指示には role ではなく systemInstruction フィールドを使用する
OpenAI 形式の assistant を model にマッピングする

APIYI（apiyi.com）を通じて迅速に動作を確認することをお勧めします。このプラットフォームは異なる API 形式の互換性問題を自動的に処理するため、ビジネスロジックの開発に集中できます。

関連情報:

Vertex AI 公式ドキュメント: cloud.google.com/vertex-ai/docs
Gemini API リファレンス: ai.google.dev/api
移行ガイド: cloud.google.com/vertex-ai/generative-ai/docs/migrate/migrate-google-ai

📝 著者: APIYI 技術チーム | AI 大規模言語モデル API の統合と最適化に注力
🔗 技術交流: APIYI apiyi.com にアクセスして、より多くの技術リソースや開発サポートをご活用ください