> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Messages API

SambaNova の Messages API (`POST /v1/messages`) は、Anthropic Messages API 標準と互換性があります。既存の Anthropic SDK クライアントは、ベース URL・API キー・モデル識別子を変更するだけで SambaNova に接続できます。このエンドポイントは、会話型・ツール対応・推論指向の連携向けに設計されています。

Messages API は、既存の Chat Completions および Responses API エンドポイントを補完するものであり、置き換えるものではありません。

## 対応モデル

Messages API は、SambaCloud および SambaStack で利用可能なすべての言語モデルに対応しています。最新の一覧は、[SambaCloud 対応モデル](/docs/ja/models/sambacloud-models) および [SambaStack 対応モデル](/docs/ja/sambastack/service-administration/model-deployment/supported-models-and-bundles) ページをご参照ください。

## 仕組み

Messages API は、モデルの出力を単一のアシスタントテキストフィールドではなく、型付きコンテンツブロック (`text`、`tool_use`、`thinking`) として構造化します。各リクエストは、モデルの動作に応じて、これらのブロックを 1 つ以上含むメッセージオブジェクトを返します。

**主な特徴:**

* **クライアント実行ツールのみ。** ツールが必要な場合、モデルは `tool_use` コンテンツブロックを返します。アプリケーション側で関数を実行し、後続のリクエストで `tool_result` コンテンツブロックとして結果を返します。サーバーサイドツールは未対応です。
* **思考 (thinking) のパススルー。** 推論対応モデルは、`text` ブロックと並んで `thinking` コンテンツブロックとして思考内容を公開します。追加のリクエストパラメータは不要です。
* **トップレベルフィールドとしてのシステムプロンプト。** Chat Completions と異なり、Anthropic スタイルのリクエストでは、システムプロンプトを `role: "system"` のメッセージとしてではなく、トップレベルの `system` フィールドで渡します。
* **構造化ストリーミング。** ストリーミング応答には、`message_start` → `content_block_start` → `content_block_delta` → `content_block_stop` → `message_delta` → `message_stop` というイベントシーケンスに従う型付き Server-Sent Events (SSE) を使用します。

## 制限事項

既存の Anthropic ベースのアプリケーションを移行する前に、以下をご確認ください。

* サーバーサイドツール (`web_search`、`code_execution`、`bash`、`text_editor`) は未対応であり、`400` エラーが返されます。クライアントで実行する関数ツールのみ利用できます。
* `document` コンテンツブロック (PDF 入力) は未対応であり、`400` エラーが返されます。
* URL 形式の画像ソースは未対応です。代わりに base64 エンコードした画像を使用してください。

## 利用方法

以下のすべての例では、SambaNova に接続した Anthropic Python SDK を使用します。`pip install anthropic` でインストールし、[Anthropic 互換性](/docs/ja/features/anthropic-compatibility) ページの手順に従って設定してください。

### シンプルな生成

```python theme={}
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.sambanova.ai/v1",
    api_key="your-sambanova-api-key"
)

message = client.messages.create(
    model="gpt-oss-120b",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain the difference between supervised and unsupervised learning in two sentences."}
    ]
)

print(message.content[0].text)
```

### ストリーミング応答

応答の生成に合わせて型付き SSE イベントを受け取るには、`client.messages.stream(...)` を使用します。

```python theme={}
with client.messages.stream(
    model="gpt-oss-120b",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Write a short poem about speed."}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
```

### 思考 (Thinking)

推論対応モデルは、`text` ブロックと並んで `thinking` コンテンツブロックとして思考内容を公開します。追加のパラメータは不要で、モデルが思考内容を生成すると自動的に返されます。

```python theme={}
response = client.messages.create(
    model="gpt-oss-120b",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "What is 27 * 43?"}
    ]
)

for block in response.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Response: {block.text}")
```

### ツール呼び出し

ツールを指定すると、モデルは `tool_use` コンテンツブロックを返すことがあります。関数の実行と結果の返却は、アプリケーション側の責務です。

**ステップ 1:** ツールを定義してリクエストを送信します。

```python theme={}
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a given location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and country, e.g. Paris, FR"
                }
            },
            "required": ["location"]
        }
    }
]

response = client.messages.create(
    model="gpt-oss-120b",
    max_tokens=1024,
    tools=tools,
    messages=[
        {"role": "user", "content": "What is the weather in Paris?"}
    ]
)

for block in response.content:
    if block.type == "tool_use":
        print(f"Tool: {block.name}, Input: {block.input}")
```

**ステップ 2:** ツールを実行し、結果を返します。この例はステップ 1 の続きで、`client`、`response`、`tools` を再利用しています。

```python theme={}
import json

def get_weather(location: str) -> dict:
    # Replace with a real weather API call
    return {"location": location, "temperature_celsius": 22, "condition": "Sunny"}

tool_use_block = next(block for block in response.content if block.type == "tool_use")
result = get_weather(tool_use_block.input["location"])

follow_up = client.messages.create(
    model="gpt-oss-120b",
    max_tokens=1024,
    tools=tools,
    messages=[
        {"role": "user", "content": "What is the weather in Paris?"},
        {"role": "assistant", "content": response.content},
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_use_block.id,
                    "content": json.dumps(result)
                }
            ]
        }
    ]
)

print(follow_up.content[0].text)
```

パラメータの一覧は [API リファレンス](/docs/ja/api-reference/overview) をご参照ください。