# API リファレンス SageMaker の Amazon Nova モデルは、推論に標準の SageMaker ランタイム API を使用します。完全な API ドキュメントについては、「[デプロイされたモデルをテストする](https://docs.aws.amazon.com//sagemaker/latest/dg/realtime-endpoints-test-endpoints.html)」を参照してください。 ## エンドポイントの呼び出し SageMaker の Amazon Nova モデルは、以下の 2 つの呼び出し方法をサポートしています。 + **同期呼び出し**: [InvokeEndpoint](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html) API をリアルタイムの非ストリーミング推論リクエストに使用します。 + **ストリーミング呼び出し**: リアルタイムストリーミング推論リクエストには [InvokeEndpointWithResponseStream](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithResponseStream.html) API を使用します。 ## リクエストの形式 Amazon Nova モデルは、以下の 2 つのリクエスト形式をサポートしています。 **チャット補完形式** 会話型インタラクションには、以下の形式を使用します。 ``` { "messages": [ {"role": "user", "content": "string"} ], "max_tokens": integer, "max_completion_tokens": integer, "stream": boolean, "temperature": float, "top_p": float, "top_k": integer, "logprobs": boolean, "top_logprobs": integer, "reasoning_effort": "low" | "high", "allowed_token_ids": [integer], "truncate_prompt_tokens": integer, "stream_options": { "include_usage": boolean } } ``` **テキスト補完形式** シンプルなテキスト生成には、以下の形式を使用します。 ``` { "prompt": "string", "max_tokens": integer, "stream": boolean, "temperature": float, "top_p": float, "top_k": integer, "logprobs": integer, "allowed_token_ids": [integer], "truncate_prompt_tokens": integer, "stream_options": { "include_usage": boolean } } ``` **マルチモーダルチャット補完形式** イメージとテキストの入力には、以下の形式を使用します。 ``` { "messages": [ { "role": "user", "content": [ {"type": "text", "text": "What's in this image?"}, {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}} ] } ], "max_tokens": integer, "temperature": float, "top_p": float, "stream": boolean } ``` **リクエストパラメータ** + `messages` (配列): チャット補完形式用。フィールド `role` と `content` フィールドを持つメッセージオブジェクトの配列。コンテンツは、テキストのみの文字列でも、マルチモーダル入力の配列でもかまいません。 + `prompt` (文字列): テキスト補完形式用。生成元の入力テキスト。 + `max_tokens` (整数): レスポンスで生成するトークンの最大数。範囲: 1 以上。 + `max_completion_tokens` (整数): チャット補完用の max\$1tokens の代替。生成する補完トークンの最大数。 + `temperature` (浮動): 生成時のランダム性を制御します。範囲: 0.0～2.0 (0.0 = 決定的、2.0 = 最大ランダム性)。 + `top_p` (浮動): Nucleus サンプリングしきい値。範囲: 1e-10～1.0。 + `top_k` (整数): 最も可能性の高い上位 K 個のトークンにトークン選択を制限します。範囲: -1 以上 (-1 = 制限なし)。 + `stream` (ブール値): レスポンスをストリーミングするかどうか。ストリーミングする場合は `true` に設定し、ストリーミングしない場合は `false` に設定します。 + `logprobs` (ブール値/整数): チャット補完の場合は、ブール値を使用します。テキスト補完の場合は、返されるログ確率の数に整数を使用します。範囲: 1～20 です。 + `top_logprobs` (整数): 確率の高い上位トークンのログ確率をいくつ返すか指定します (チャットの完了のみ)。 + `reasoning_effort` (文字列): 推論の労力のレベル。オプション:「low」、「high」(Nova 2 Lite カスタムモデルのチャット完了のみ)。 + `allowed_token_ids` (配列): 生成できるトークン ID のリスト。指定されたトークンへの出力を制限します。 + `truncate_prompt_tokens` (整数): 制限を超えた場合は、この数のトークンにプロンプトを切り捨てます。 + `stream_options` (オブジェクト): ストリーミングレスポンスのオプション。ストリーミングレスポンスにトークン使用量を含める `include_usage` ブール値が含まれます。 ## レスポンスの形式 レスポンスの形式は、呼び出し方法とリクエストタイプによって異なります。 **チャット補完レスポンス (非ストリーミング)** 同期チャット補完リクエストの場合: ``` { "id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000", "object": "chat.completion", "created": 1677652288, "model": "nova-micro-custom", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! I'm doing well, thank you for asking. How can I help you today?", "refusal": null, "reasoning": null, "reasoning_content": null }, "logprobs": { "content": [ { "token": "Hello", "logprob": -0.31725305, "bytes": [72, 101, 108, 108, 111], "top_logprobs": [ { "token": "Hello", "logprob": -0.31725305, "bytes": [72, 101, 108, 108, 111] }, { "token": "Hi", "logprob": -1.3190403, "bytes": [72, 105] } ] } ] }, "finish_reason": "stop", "stop_reason": null, "token_ids": [9906, 0, 358, 2157, 1049, 11, 1309, 345, 369, 6464, 13] } ], "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21, "prompt_tokens_details": { "cached_tokens": 0 } }, "prompt_token_ids": [9906, 0, 358] } ``` **テキスト補完レスポンス (非ストリーミング)** 同期テキスト補完リクエストの場合: ``` { "id": "cmpl-123e4567-e89b-12d3-a456-426614174000", "object": "text_completion", "created": 1677652288, "model": "nova-micro-custom", "choices": [ { "index": 0, "text": "Paris, the capital and most populous city of France.", "logprobs": { "tokens": ["Paris", ",", " the", " capital"], "token_logprobs": [-0.31725305, -0.07918124, -0.12345678, -0.23456789], "top_logprobs": [ { "Paris": -0.31725305, "London": -1.3190403, "Rome": -2.1234567 }, { ",": -0.07918124, " is": -1.2345678 } ] }, "finish_reason": "stop", "stop_reason": null, "prompt_token_ids": [464, 6864, 315, 4881, 374], "token_ids": [3915, 11, 279, 6864, 323, 1455, 95551, 3363, 315, 4881, 13] } ], "usage": { "prompt_tokens": 5, "completion_tokens": 11, "total_tokens": 16, "prompt_tokens_details": { "cached_tokens": 0 } } } ``` **チャット補完ストリーミングレスポンス** ストリーミングチャット補完リクエストの場合、レスポンスはサーバー送信イベント (SSE) として送信されます。 ``` data: { "id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000", "object": "chat.completion.chunk", "created": 1677652288, "model": "nova-micro-custom", "choices": [ { "index": 0, "delta": { "role": "assistant", "content": "Hello", "refusal": null, "reasoning": null, "reasoning_content": null }, "logprobs": { "content": [ { "token": "Hello", "logprob": -0.31725305, "bytes": [72, 101, 108, 108, 111], "top_logprobs": [ { "token": "Hello", "logprob": -0.31725305, "bytes": [72, 101, 108, 108, 111] } ] } ] }, "finish_reason": null, "stop_reason": null } ], "usage": null, "prompt_token_ids": null } data: { "id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000", "object": "chat.completion.chunk", "created": 1677652288, "model": "nova-micro-custom", "choices": [ { "index": 0, "delta": { "content": "! I'm" }, "logprobs": null, "finish_reason": null, "stop_reason": null } ], "usage": null } data: { "id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000", "object": "chat.completion.chunk", "created": 1677652288, "model": "nova-micro-custom", "choices": [ { "index": 0, "delta": {}, "finish_reason": "stop", "stop_reason": null } ], "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21, "prompt_tokens_details": { "cached_tokens": 0 } } } data: [DONE] ``` **テキスト補完ストリーミングレスポンス** ストリーミングテキスト補完リクエストの場合: ``` data: { "id": "cmpl-123e4567-e89b-12d3-a456-426614174000", "object": "text_completion", "created": 1677652288, "model": "nova-micro-custom", "choices": [ { "index": 0, "text": "Paris", "logprobs": { "tokens": ["Paris"], "token_logprobs": [-0.31725305], "top_logprobs": [ { "Paris": -0.31725305, "London": -1.3190403 } ] }, "finish_reason": null, "stop_reason": null } ], "usage": null } data: { "id": "cmpl-123e4567-e89b-12d3-a456-426614174000", "object": "text_completion", "created": 1677652288, "model": "nova-micro-custom", "choices": [ { "index": 0, "text": ", the capital", "logprobs": null, "finish_reason": null, "stop_reason": null } ], "usage": null } data: { "id": "cmpl-123e4567-e89b-12d3-a456-426614174000", "object": "text_completion", "created": 1677652288, "model": "nova-micro-custom", "choices": [ { "index": 0, "text": "", "finish_reason": "stop", "stop_reason": null } ], "usage": { "prompt_tokens": 5, "completion_tokens": 11, "total_tokens": 16 } } data: [DONE] ``` **レスポンスフィールドの説明** + `id`: 補完の一意の識別子 + `object`: 返されるオブジェクトのタイプ ("chat.completion"、"text\$1completion"、"chat.completion.chunk") + `created`: 補完が作成された時刻の Unix タイムスタンプ + `model`: 補完に使用されるモデル + `choices`: 補完選択肢の配列 + `usage`: プロンプト、補完、合計トークンを含むトークン使用状況情報 + `logprobs`: トークンのログ確率情報 (リクエストされた場合) + `finish_reason`: モデルが生成を停止した理由 ("stop"、"length"、"content\$1filter") + `delta`: ストリーミングレスポンスの増分コンテンツ + `reasoning`: reasoning\$1effort を使用する場合の推論コンテンツ + `token_ids`: 生成されたテキストのトークン ID の配列 完全な API ドキュメントについては、「[InvokeEndpoint API リファレンス](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html)」および「[InvokeEndpointWithResponseStream API リファレンス](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithResponseStream.html)」を参照してください。