API リクエストの形式を設定する

このページでは、OpenAI Chat Completions エンドポイントのリクエスト本文の詳細を使用して、Google Distributed Cloud（GDC）エアギャップ上の Gemini の API リクエストをフォーマットする方法について説明します。この形式に準拠することで、OpenAI API の構造を使用しながら、Gemini の高度な機能をアプリケーションにシームレスに統合できます。

Gemini モデル ファミリーには、マルチモーダル プロンプト リクエストに対応するモデルが含まれています。マルチモーダルとは、プロンプトで複数のモダリティ（入力タイプ）を使用できることを示します。詳細については、プロンプトを設計するをご覧ください。

gRPC ライブラリ用に生成される型、メソッド、フィールドの一般的な説明については、Gemini gRPC リファレンスをご覧ください。

始める前に

API リクエストの形式を設定する前に、次の前提条件を満たしていることを確認してください。

  • GDC での Gemini の機能について学習する。
  • Gemini の API リクエストを行うための最小限のプロジェクト要件を確認する。
  • リクエストで使用する Gemini モデルのエンドポイント ID を特定します。特定のモデルを選択すると、そのモデルの独自の機能をタスクに使用できます。GDC で利用可能な Gemini モデルをご覧ください。
  • Gemini から期待どおりの回答を引き出すために、プロンプトを慎重に作成する方法を理解する。さまざまなプロンプト スタイルと形式を試して、出力を最適化します。詳細については、プロンプトの概要をご覧ください。
  • OpenAI Chat Completions エンドポイントで使用可能なさまざまなパラメータを確認して、Gemini の動作を制御します。temperature、max_completion_tokens、top_p などのパラメータを調整して、生成されるテキストの創造性、長さ、多様性を制御します。詳細については、パラメータを試すをご覧ください。

リクエストの構文

次の例には、モデル レスポンスを生成するために API リクエストで使用する必要がある構文が含まれています。

Python

import openai

client = openai.OpenAI()
model_response = client.chat.completions.create(
  model = "MODEL_ID",
  messages = [
    {
      ...
    }
  ]
  ...
)

print(model_response)

curl

curl \
  -X POST "https://ENDPOINT:443/v1/projects/PROJECT/locations/PROJECT/chat/completions" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer $(gdcloud auth print-identity-token)" \
  -d '{
      "model_id": "MODEL_ID",
      "messages" = [
        {
          ...
        }
      ]
      ...
  }'

API パラメータ

このセクションでは、GDC の Gemini の API リクエストのリクエスト本文で定義できる最も重要なパラメータと、モデルが返す必要のあるレスポンス本文のリストを示します。OpenAI の Chat Completions エンドポイントの完全な API リファレンスについては、https://platform.openai.com/docs/api-reference/chat をご覧ください。

リクエストの本文

{
  "messages" = [
    {
      "role": string,
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": string
          }
        },
        {
          "type": "input_audio",
          "input_audio": {
            "data": string,
            "format": string
          }
        },
        {
          "type": "audio_url",
          "audio_url": {
            "url": string
          }
        },
        {
          "type": "input_video",
          "input_video": {
            "data": string,
            "format": string
          }
        },
        {
          "type": "video_url",
          "video_url": {
            "url": string
          }
        },
        {
          "type": "input_document",
          "input_document": {
            "data": string,
            "format": string
          }
        },
        {
          "type": "document_url",
          "document_url": {
            "url": string
          }
        }
      ]
    }
  ],
  "temperature": number,
  "max_completion_tokens": integer,
  "top_p": number,
  "n": integer,
  "stop": string,
  "user": string
}

次の表に、Gemini で使用する場合の OpenAI Chat Completions エンドポイントのリクエスト本文のキーフィールドとその説明を示します。

パラメータ
フィールド名 説明

model

必須: string

使用する Gemini モデル。

詳細については、利用可能な Gemini モデルをご覧ください。

messages

必須: object

モデルとの現在の会話を構成するメッセージのリスト。各メッセージには role と content があります。

テキスト、画像、音声、動画、ドキュメントなど、さまざまなメッセージ タイプ（モダリティ）がサポートされています。

role

必須: string

メッセージ作成者のロール。次のいずれかになります。

  • system: ユーザーが送信したメッセージに関係なく、モデルが従う必要があるシステム提供の指示。
  • user: モデルが応答する必要がある、ユーザーが提供したメッセージ。プロンプトや追加のコンテキスト情報が含まれています。
  • assistant: ユーザー メッセージに対するレスポンスとしてモデルから提供されるメッセージ。

content

必須: string または array

システム、ユーザー、アシスタントからのメッセージの内容。

シングルターン クエリの場合、値は単一のインスタンスです。マルチターン クエリの場合、content は会話履歴と最新のリクエストを含む繰り返しフィールドです。詳しくは、content をご覧ください。

temperature

省略可: number または null

生成されたテキストのランダム性。

値が低い（0 に近い）ほど、より決定的で焦点を絞ったレスポンスが得られます。一方、値が高い（2 に近い）ほど、より多様で創造的な出力が得られます。

デフォルトは 1 です。

max_completion_tokens

省略可: integer または null

レスポンスで生成するトークンの最大数。これには、表示可能な出力トークンと推論トークンが含まれます。

top_p

省略可: number または null

Nucleus サンプリングの確率。

値が高いほど（1 に近いほど）、より広範囲の潜在的なトークンからサンプリングされ、値が低いほど（0 に近いほど）、最も可能性の高いトークンに焦点が当てられます。

デフォルトは 1 です。

n

省略可: integer または null

プロンプトごとに生成する補完の数。

デフォルトは 1 です。

stop

省略可: string、array、null

検出された場合にテキスト生成プロセスを停止する文字列のリスト。

デフォルトは null です。

user

省略可: string

エンドユーザーの一意の識別子。

このパラメータを使用すると、使用パターンを追跡し、回答をパーソナライズできます。

content

このフィールドは、メッセージのマルチパート コンテンツを含む基本的な構造化データ型です。

入力がテキスト プロンプトの場合、このフィールドの値は文字列です。ただし、マルチモーダル プロンプトの場合、このフィールドは、各オブジェクトに type と INPUT の 2 つの主要なプロパティを含む配列で構成されます。type プロパティはマルチモーダル入力のコンテンツのタイプを表し、INPUT プロパティには、base64 エンコード データまたは GDC ストレージ バケットの URL として表される入力要素が含まれます。

次の表に、マルチモーダル プロンプトの主要な content フィールドとその説明を示します。

フィールド名 説明

type

必須: string

マルチモーダル プロンプトのコンテンツ タイプ。指定できる値は次のとおりです。

  • image_url: 入力コンテンツは、base64 エンコード データまたは GDC ストレージ バケットの URL として提供される画像です。
  • input_audio: 入力コンテンツは、base64 でエンコードされたデータとして提供される音声です。
  • audio_url: 入力コンテンツは、GDC ストレージ バケットから URL として提供される音声です。
  • input_video: 入力コンテンツは、Base64 エンコード データとして提供される動画です。
  • video_url: 入力コンテンツは、GDC ストレージ バケットから URL として提供される動画です。
  • input_document: 入力コンテンツは、base64 でエンコードされたデータとして提供されるドキュメントです。
  • document_url: 入力コンテンツは、GDC ストレージ バケットから URL として提供されるドキュメントです。

INPUT

必須: object

マルチモーダル プロンプトのコンテンツ入力。このフィールド名は、type フィールドで指定された値と同じである必要があります。

したがって、このフィールド名は次のいずれかになります。

  • 画像の場合: image_url
  • 音声の場合: input_audio または audio_url
  • 動画の場合: input_video または video_url
  • ドキュメントの場合: input_document または document_url。

各入力フィールドには、url または data と format があります。

url

省略可: string

入力コンテンツが URL として指定されている場合は、GDC ストレージ バケット内のファイルへのパス。

画像の場合、このフィールドには URL ではなく base64 でエンコードされたデータを含めることができます。

data

省略可: string

入力コンテンツが base64 でエンコードされたデータとして提供されている場合、バイナリデータは文字列に変換されます。

画像の場合は、代わりに url フィールドに base64 でエンコードされたデータが提供されます。

format

省略可: string

入力コンテンツが data フィールドで指定されている場合、指定されたデータの形式仕様。

入力データに応じて、さまざまな形式がサポートされています。詳細については、画像、音声、動画、ドキュメントの MIME タイプをご覧ください。

レスポンスの本文

{
  "id": string,
  "object": string,
  "created": integer,
  "model": string,
  "choices": [
    {
      "index": integer,
      "message": {
        "role": string,
        "content": string,
        "refusal": null
      },
      "logprobs": null,
      "finish_reason": string
    }
  ],
  "usage": {
    "completion_tokens": integer,
    "prompt_tokens": integer,
    "total_tokens": integer
  },
  "system_fingerprint": string
}

次の表に、指定された入力に基づいてモデルから返されるレスポンス本文のキーフィールドとその説明を示します。

フィールド名 説明

id

string

生成されたテキストの一意の識別子。

object

string

オブジェクト タイプ。常に chat.completion です。

created

integer

テキストが生成されたときのタイムスタンプ（秒単位）。

model

string

テキストの生成に使用されるモデル。

choices

array

テキスト生成の選択肢のリスト。n が 1 より大きい場合、このフィールドには複数の選択肢を含めることができます。

index

integer

選択肢のリスト内の選択肢のインデックス。

message

object

モデルによって生成されたテキスト生成メッセージ。このフィールドには次のプロパティが含まれます。

  • role:（string）メッセージ作成者のロール。
  • content:（string または null）メッセージの内容。
  • refusal:（string または null）モデルによって生成された拒否メッセージ。

logprobs

object または null

選択肢の対数確率情報。

finish_reason

string

モデルがトークンの生成を停止した理由。値は次のいずれかです。

  • stop: モデルが自然な停止点または指定された停止シーケンスに達します。
  • length: リクエストで指定されたトークンの最大数に達しました。
  • content_filter: コンテンツ フィルタのフラグにより、コンテンツが省略されています。
  • tool_calls: ツールと呼ばれるモデル。

usage

object

リクエストの使用状況の統計情報。

completion_tokens

integer

生成されたテキストのトークン数。

prompt_tokens

integer

プロンプト内のトークン数。

total_tokens

integer

プロンプトと生成されたテキストのトークンの合計数。

system_fingerprint

string

モデルが実行に使用するバックエンド構成。

例

このセクションでは、リクエストの本文と、モデルが返す必要があるテキスト生成レスポンスの例を示します。

リクエストの例

次の例は、Gemini にプロンプトを送信してテキストを生成するリクエスト本文の詳細を示しています。この例には、温度と最大トークン数の制御が含まれています。実装の詳細については、テキスト プロンプトを送信するまたはマルチモーダル プロンプトを送信するをご覧ください。

{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful and informative assistant."
    },
    {
      "role": "user",
      "content": "What is the capital of France?"
    }
  ],
  "temperature": 0.7,
  "max_completion_tokens": 100
}

レスポンスの例

次の例は、モデルから返されたテキスト生成レスポンスの詳細を示しています。

{
  "id": "",
  "object": "",
  "created": 0,
  "model": "",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris.\n",
        "refusal": null
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "completion_tokens": 7,
    "prompt_tokens": 8,
    "total_tokens": 15
  },
  "system_fingerprint": ""
}

次のステップ