> ## 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.

# Responses API

SambaNova の Responses API (`POST /v1/responses`) は、OpenAI Responses API 標準と互換性があります。OpenAI Responses API 向けに構築された既存のクライアントや SDK は、コードを変更することなく SambaNova のエンドポイントに接続できます。このエンドポイントは、エージェント型・ツール対応・コーディング指向の連携向けに設計されています。

Responses API は、既存の Chat Completions API を補完するものであり、置き換えるものではありません。

## 対応モデル

* `gpt-oss-120b`
* `MiniMax-M2.7`
* `MiniMax-M3`
* `gemma-4-31B-it`

今後のリリースで、さらにモデルが追加される予定です。

<Note>
  `gpt-oss-120b` でツール呼び出しリクエストの品質を高めるには、`reasoning_effort` を `high` に設定してください。
</Note>

## 仕組み

Responses API は、モデルの出力を単一のアシスタントテキストフィールドではなく、型付き出力アイテム (`message`、`function_call`、`reasoning`) として構造化します。各リクエストは、モデルの動作に応じて、これらのアイテムを 1 つ以上含むレスポンスオブジェクトを返します。

## 主な特徴

**ステートレス**: SambaNova は会話の状態を保存しません。マルチターン会話を継続するには、後続の各リクエストの input 配列に、関連する過去の出力アイテムを含めてください。

**クライアント実行ツールのみ**: ツールが必要な場合、モデルは `function_call` アイテムを返します。アプリケーション側で関数を実行し、後続のリクエストで結果を返します。組み込みツールおよびサーバー実行ツールは未対応です。

**構造化ストリーミング**: ストリーミング応答には、`event` → `item` → `content` → `delta` のイベント階層を持つ型付き Server-Sent Events (SSE) を使用します。

**構造化出力**: `text.format` フィールドは、`json_schema` および `json_object` 形式タイプに対応しています。

**推論対応**: 推論対応モデルは、`reasoning` 出力アイテムとして推論内容を公開します。

## 利用方法

### シンプルな生成

<CodeGroup>
  ```python Python (SambaNova) theme={}
  from sambanova import SambaNova
  client = SambaNova(
      base_url="your-sambanova-base-url",
      api_key="your-sambanova-api-key"
  )
  response = client.responses.create(
      model="gpt-oss-120b",
      input="Explain the difference between supervised and unsupervised learning in two sentences."
  )
  print(response.output[0].content[0].text)
  # or
  print(response.output_text)
  ```

  ```python Python (OpenAI) theme={}
  from openai import OpenAI
  client = OpenAI(
      base_url="your-sambanova-base-url",
      api_key="your-sambanova-api-key"
  )
  response = client.responses.create(
      model="gpt-oss-120b",
      input="Explain the difference between supervised and unsupervised learning in two sentences."
  )
  print(response.output[0].content[0].text)
  # or
  print(response.output_text)
  ```
</CodeGroup>

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

応答の生成に合わせて型付き SSE イベントを受け取るには、`stream=True` を設定します。

<CodeGroup>
  ```python Python (SambaNova) theme={}
  from sambanova import SambaNova
  client = SambaNova(
      base_url="your-sambanova-base-url",
      api_key="your-sambanova-api-key"
  )
  stream = client.responses.create(
      model="gpt-oss-120b",
      input="Write a short poem about speed.",
      stream=True
  )
  for event in stream:
      if event.type == "response.output_text.delta":
          print(event.delta, end="", flush=True)
  ```

  ```python Python (OpenAI) theme={}
  from openai import OpenAI
  client = OpenAI(
      base_url="your-sambanova-base-url",
      api_key="your-sambanova-api-key"
  )
  stream = client.responses.create(
      model="gpt-oss-120b",
      input="Write a short poem about speed.",
      stream=True
  )
  for event in stream:
      if event.type == "response.output_text.delta":
          print(event.delta, end="", flush=True)
  ```
</CodeGroup>

### Function calling

ツールを指定すると、モデルはメッセージの代わりに `function_call` アイテムを返すことがあります。関数の実行と結果の返却は、アプリケーション側の責務です。

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

<CodeGroup>
  ```python Python (SambaNova) theme={}
  from sambanova import SambaNova
  client = SambaNova(
      base_url="your-sambanova-base-url",
      api_key="your-sambanova-api-key"
  )
  tools = [
      {
          "type": "function",
          "name": "get_weather",
          "description": "Get the current weather for a city.",
          "parameters": {
              "type": "object",
              "properties": {
                  "city": {
                      "type": "string",
                      "description": "The city name, e.g. San Francisco"
                  }
              },
              "required": ["city"]
          }
      }
  ]
  response = client.responses.create(
      model="gpt-oss-120b",
      input=[{"role": "user", "content": "What is the weather in Bogotá?"}],
      tools=tools
  )
  for item in response.output:
      if item.type == "function_call":
          print(f"Tool: {item.name}, Arguments: {item.arguments}")
  ```

  ```python Python (OpenAI) theme={}
  from openai import OpenAI
  client = OpenAI(
      base_url="your-sambanova-base-url",
      api_key="your-sambanova-api-key"
  )
  tools = [
      {
          "type": "function",
          "name": "get_weather",
          "description": "Get the current weather for a city.",
          "parameters": {
              "type": "object",
              "properties": {
                  "city": {
                      "type": "string",
                      "description": "The city name, e.g. San Francisco"
                  }
              },
              "required": ["city"]
          }
      }
  ]
  response = client.responses.create(
      model="gpt-oss-120b",
      input=[{"role": "user", "content": "What is the weather in Bogotá?"}],
      tools=tools
  )
  # Print the function_call items returned by the model
  for item in response.output:
      if item.type == "function_call":
          print(f"Tool: {item.name}, Arguments: {item.arguments}")
  ```
</CodeGroup>

**ステップ 2**: ツールを実行し、結果を返します (ステップ 1 の `client`、`response`、`tools` を使用します)

<CodeGroup>
  ```python Python (SambaNova) theme={}
  import json
  def get_weather(city: str) -> dict:
      # Replace with a real weather API call
      return {"city": city, "temperature_celsius": 18, "condition": "Cloudy"}
  # Find the function_call item in the response
  tool_call = next(item for item in response.output if item.type == "function_call")
  args = json.loads(tool_call.arguments)
  result = get_weather(args["city"])
  # Submit the tool result in a follow-up request
  follow_up = client.responses.create(
      model="gpt-oss-120b",
      input=[
          {"role": "user", "content": "What is the weather in Bogotá?"},
          tool_call,
          {
              "type": "function_call_output",
              "call_id": tool_call.call_id,
              "output": json.dumps(result)
          }
      ],
      tools=tools
  )
  print(follow_up.output[0].content[0].text)
  ```

  ```python Python (OpenAI) theme={}
  import json
  def get_weather(city: str) -> dict:
      # Replace with a real weather API call
      return {"city": city, "temperature_celsius": 18, "condition": "Cloudy"}
  # Find the function_call item in the response
  tool_call = next(item for item in response.output if item.type == "function_call")
  args = json.loads(tool_call.arguments)
  result = get_weather(args["city"])
  # Submit the tool result in a follow-up request
  follow_up = client.responses.create(
      model="gpt-oss-120b",
      input=[
          {"role": "user", "content": "What is the weather in Bogotá?"},
          tool_call,
          {
              "type": "function_call_output",
              "call_id": tool_call.call_id,
              "output": json.dumps(result)
          }
      ],
      tools=tools
  )
  print(follow_up.output[0].content[0].text)
  ```
</CodeGroup>

### 構造化出力

応答を JSON スキーマに制約するには、`text.format` フィールドを使用します。

<CodeGroup>
  ```python Python (SambaNova) theme={}
  import json
  from sambanova import SambaNova
  client = SambaNova(
      base_url="your-sambanova-base-url",
      api_key="your-sambanova-api-key"
  )
  response = client.responses.create(
      model="gpt-oss-120b",
      input="Extract the event details: SambaNova launch on May 1, 2026 at 10am in San Francisco.",
      text={
          "format": {
              "type": "json_schema",
              "name": "event_extraction",
              "schema": {
                  "type": "object",
                  "properties": {
                      "title": {"type": "string"},
                      "date": {"type": "string"},
                      "time": {"type": "string"},
                      "location": {"type": "string"}
                  },
                  "required": ["title", "date", "time", "location"],
                  "additionalProperties": False
              }
          }
      }
  )
  print(json.loads(response.output[0].content[0].text))
  ```

  ```python Python (OpenAI) theme={}
  import json
  from openai import OpenAI
  client = OpenAI(
      base_url="your-sambanova-base-url",
      api_key="your-sambanova-api-key"
  )
  response = client.responses.create(
      model="gpt-oss-120b",
      input="Extract the event details: SambaNova launch on May 1, 2026 at 10am in San Francisco.",
      text={
          "format": {
              "type": "json_schema",
              "name": "event_extraction",
              "schema": {
                  "type": "object",
                  "properties": {
                      "title": {"type": "string"},
                      "date": {"type": "string"},
                      "time": {"type": "string"},
                      "location": {"type": "string"}
                  },
                  "required": ["title", "date", "time", "location"],
                  "additionalProperties": False
              }
          }
      }
  )
  print(json.loads(response.output[0].content[0].text))
  ```
</CodeGroup>

### マルチターン会話

Responses API はステートレスです。複数ターンにわたってコンテキストを維持するには、後続の各リクエストの input 配列に、新しいユーザーメッセージと併せて過去のすべての出力アイテムを含めてください。

<CodeGroup>
  ```python Python (SambaNova) theme={}
  from sambanova import SambaNova
  client = SambaNova(
      base_url="your-sambanova-base-url",
      api_key="your-sambanova-api-key"
  )
  # First turn
  response_1 = client.responses.create(
      model="gpt-oss-120b",
      input=[{"role": "user", "content": "What is the capital of Colombia?"}]
  )
  assistant_message = response_1.output[0]
  # Second turn – include prior output items
  response_2 = client.responses.create(
      model="gpt-oss-120b",
      input=[
          {"role": "user", "content": "What is the capital of Colombia?"},
          assistant_message,
          {"role": "user", "content": "What is its approximate population?"}
      ]
  )
  print(response_2.output[0].content[0].text)
  ```

  ```python Python (OpenAI) theme={}
  from openai import OpenAI
  client = OpenAI(
      base_url="your-sambanova-base-url",
      api_key="your-sambanova-api-key"
  )
  # First turn
  response_1 = client.responses.create(
      model="gpt-oss-120b",
      input=[{"role": "user", "content": "What is the capital of Colombia?"}]
  )
  assistant_message = response_1.output[0]
  # Second turn – include prior output items
  response_2 = client.responses.create(
      model="gpt-oss-120b",
      input=[
          {"role": "user", "content": "What is the capital of Colombia?"},
          assistant_message,
          {"role": "user", "content": "What is its approximate population?"}
      ]
  )
  print(response_2.output[0].content[0].text)
  ```
</CodeGroup>

## 制限事項

* `previous_response_id` パラメータは未対応です。SambaNova Responses API はステートレスであるため、過去の出力アイテムを input 配列に含めることで会話履歴を管理してください。
* 組み込みツールおよびサーバー実行ツールは未対応です。クライアントで実行する関数ツールのみ利用できます。