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

# Responses API

> エンドポイント POST /v1/responses (OpenAI Responses API 互換) - Codex CLI、OpenAI Agents SDK、または API キー Hostlinku を使用した client.responses.create() を使用してください

Hostlinku は、[OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) - **Codex CLI** で使用されるフォーマット - と互換性のあるエンドポイントを提供します。 **OpenAI Agents SDK**、およびOpenAI SDKの`client.responses.create()`メソッドで使用されるフォーマットです。 base URL を変更するだけで済みます。API キー、残高、Service Mode、レート制限、およびリクエストログは、`/v1/chat/completions` および `/v1/messages` と同じです。

```http theme={null}
POST https://api.hostlinku.com/v1/responses
Authorization: Bearer sk-your-api-key
Content-Type: application/json
```

すべての応答には、ヘッダー `x-request-id`（リクエスト ID Hostlinku、フォーマット `resp_…`）が含まれており、非ストリーミングの成功応答には `x-model` が含まれます。

すべてのモデル、1つのフォーマット

`model`は、[モデルカタログ](https://docs.hostlinku.com/ja/models.md)と同じパブリックslug「Hostlinku」を使用しています。例：`gpt-5-5`、`claude-sonnet-4-6`、`deepseek-v4-flash`。 Responses APIをネイティブで提供していないモデル（Claudeを含む）も、ゲートウェイが変換を行うことで呼び出すことができます。

## クイック設定

各ツールの詳細なガイドは、[Codex CLI](https://docs.hostlinku.com/ja/integrations/codex-cli.md) および [OpenAI Agents SDK](https://docs.hostlinku.com/ja/integrations/agents-sdk.md) に掲載されています。

**Codex CLI** (`~/.codex/config.toml`)

```toml theme={null}
model = "gpt-5-5"
model_provider = "hostlinku"

[model_providers.hostlinku]
name = "Hostlinku"
base_url = "https://api.hostlinku.com/v1"
env_key = "HOSTLINKU_API_KEY"
wire_api = "responses"
```

```bash theme={null}
export HOSTLINKU_API_KEY=sk-your-api-key
codex
```

**Python（OpenAI公式SDK）**

```python theme={null}
from openai import OpenAI

client = OpenAI(api_key="sk-your-api-key", base_url="https://api.hostlinku.com/v1")

response = client.responses.create(
    model="gpt-5-5",
    instructions="Jawab singkat dalam bahasa Indonesia.",
    input="Apa itu API gateway?",
    max_output_tokens=256,
)
print(response.output_text)
print(response.usage.input_tokens, response.usage.output_tokens)
```

**Node.js**

```ts theme={null}
import OpenAI from "openai";

const client = new OpenAI({ apiKey: "sk-your-api-key", baseURL: "https://api.hostlinku.com/v1" });
const response = await client.responses.create({
  model: "claude-sonnet-4-6",
  input: "Halo!",
  max_output_tokens: 256,
});
console.log(response.output_text);
```

**OpenAI Agents SDK (Python)**

```python theme={null}
from agents import Agent, Runner, set_default_openai_client, set_tracing_disabled
from openai import AsyncOpenAI

set_default_openai_client(AsyncOpenAI(api_key="sk-your-api-key", base_url="https://api.hostlinku.com/v1"))
set_tracing_disabled(True)  # tracing OpenAI tidak tersedia lewat gateway

agent = Agent(name="Asisten", instructions="Jawab singkat.", model="gpt-5-5")
result = Runner.run_sync(agent, "Sebutkan 3 bahasa pemrograman.")
print(result.final_output)
```

## bodyパラメータ

| パラメータ | タイプ | 説明 |
| - | - | - |
| `model` | `string` | **必須。** slug型番 Hostlinku。 |
| `input` | `string` \| `array` | **必須。** 単一のテキスト、または配列の項目：`message`（`role` + `content` には `input_text`/`input_image`/…が含まれる）、 `function_call`、`function_call_output`、`reasoning`。 |
| `instructions` | `string` | システムプロンプト（開発者向けメッセージ）。 |
| `max_output_tokens` | `integer` | 出力トークンの上限。モデルの出力上限を超えた場合、`400`として拒否されます。 |
| `stream` | `boolean` | SSE用の`true`（下記参照）。 |
| `tools`, `tool_choice`, `parallel_tool_calls` | - | 関数呼び出し形式 Responses (`{ "type": "function", "name", "parameters" }`)。 |
| `reasoning` | `object` | 例：`{ "effort": "low" \| "medium" \| "high", "summary": "auto" }`。 |
| `include` | `string[]` | 例：`["reasoning.encrypted_content"]` - 暗号化された項目推論は、次のターンで再送信できるよう、そのままの状態で返されます（Codex CLIで使用）。 |
| `text`, `truncation`, `temperature`, `top_p`, `metadata`, `user`, `prompt_cache_key`, `safety_identifier` | - | OpenAIの仕様に準拠；モデルに反映済み。 |
| `store` | `boolean` | 常に `false` として扱われます（*Stateless* を参照）。 |
| `previous_response_id`, `conversation`, `background` | - | **未対応** → `400 invalid_request_error`。 |

認識されないその他のフィールドはゲートウェイに転送されます（モデルでサポートされていないパラメータは無視されます）。無効なボディは`400 invalid_request_error`として拒否され、フィールドごとの詳細は`error.details.issues`に記載されています。

Stateless - `input`に完全な履歴を送信

Hostlinku **は** レスポンス（`store: false`）を保存しません。 複数ターンにわたる会話の場合、`input`配列に履歴全体（以前の応答に含まれる`function_call`、`function_call_output`、および`reasoning`の項目を含む）を送信してください。これは、Codex CLIの動作とまったく同じです。 `previous_response_id`は明確なメッセージで拒否され、`GET`/`DELETE /v1/responses/{id}`は`404`に応答します。

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

```json theme={null}
{
  "id": "resp_…",
  "object": "response",
  "created_at": 1791850828,
  "completed_at": 1791850829,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "model": "gpt-5-5",
  "output": [
    { "id": "rs_…", "type": "reasoning", "summary": [], "encrypted_content": "…" },
    {
      "id": "msg_…",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "API gateway adalah …", "annotations": [] }]
    }
  ],
  "usage": {
    "input_tokens": 20,
    "output_tokens": 19,
    "total_tokens": 39,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens_details": { "reasoning_tokens": 12 }
  },
  "previous_response_id": null,
  "store": false,
  "hostlinku": { "cost": 0.00031, "currency": "🪙", "serviceMode": "performance", "latencyMs": 1420 }
}
```

`id` および `model` は、常に Hostlinku のパブリック ID です。 ブロック`hostlinku`は拡張情報（OpenAIのSDKはこれを無視する）であり、kredit、Service Mode API keyの費用およびレイテンシが含まれている。 `status: "incomplete"` および `incomplete_details.reason = "max_output_tokens"` は、出力が `max_output_tokens` によって切り詰められていることを意味しますが、実際のトークンに基づいて課金されます。

推論モデル + `max_output_tokens`（小型）

推論モデル（例：DeepSeek V4、GPT-6、思考機能付きClaude）では、思考トークンも`max_output_tokens`にカウントされます。 小さい値（例：`16`）は通常、`reasoning`の項目のみに割り当てられる → `status: "incomplete"`および`output`には、`message`を含まない`reasoning`の項目のみが含まれる。 `max_output_tokens` ≥ 256 を使用するか、`reasoning.effort` を `"low"` に下げる。

Responses API の使用規約

Chat Completionsと同様に、`input_tokens`にはキャッシュトークンが**すでに含まれています**。詳細については`input_tokens_details.cached_tokens`を参照してください。`output_tokens`には`reasoning_tokens`が含まれています。 請求書Hostlinkuは、これらの構成要素についてそれぞれの価格に基づいて計算されます（[請求](https://docs.hostlinku.com/ja/billing.md)を参照）。

## ストリーミング (`stream: true`)

ゲートウェイは、Responses API（`event:` + `data:`）のフレーム形式でSSEイベントを転送します。これには、アップストリームからの`sequence_number`も含まれます：

```text theme={null}
event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"id":"resp_…","object":"response","status":"in_progress","model":"gpt-5-5","output":[],…}}

event: response.in_progress
data: {"type":"response.in_progress","sequence_number":1,"response":{…}}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":2,"output_index":0,"item":{"id":"msg_…","type":"message","status":"in_progress","role":"assistant","content":[]}}

event: response.content_part.added
data: {"type":"response.content_part.added","sequence_number":3,"item_id":"msg_…","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":4,"item_id":"msg_…","output_index":0,"content_index":0,"delta":"API gateway"}

event: response.output_text.done
data: {"type":"response.output_text.done","sequence_number":5,"item_id":"msg_…","output_index":0,"content_index":0,"text":"API gateway adalah …"}

event: response.content_part.done
data: {"type":"response.content_part.done","sequence_number":6,…}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":7,"output_index":0,"item":{"id":"msg_…","type":"message","status":"completed",…}}

event: response.completed
data: {"type":"response.completed","sequence_number":8,"response":{"id":"resp_…","status":"completed","model":"gpt-5-5","output":[…],"usage":{"input_tokens":20,"output_tokens":19,"total_tokens":39,…}}}
```

注：

* 最終的な使用量は、`response.completed`（または`response.incomplete`）のオブジェクト`response`に記録されます。費用は、そのイベント後の実際の使用量に基づいて計算されます。
* ツールコールは、`response.output_item.added`（`type: "function_call"`）、`response.function_call_arguments.delta`、および`response.function_call_arguments.done`を経由して送信されます。
* ストリームが途中で失敗した場合、ゲートウェイは`event: error`と`{"type":"error","code":…,"message":…}`を送信し、偽の`response.completed`は**送信しない**。
* 最初のバイトが送信される前のエラー（残高不足、モデルが存在しない、レート制限）は、正しいHTTPステータスを伴う通常のJSONレスポンスとして返されます。SDK OpenAIでは、これらを例外（`AuthenticationError`、`NotFoundError`、 `RateLimitError`、…）。

## ツールの呼び出し（関数の呼び出し）

```python theme={null}
tools = [{
    "type": "function",
    "name": "get_time",
    "description": "Waktu saat ini di sebuah kota",
    "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}]

r1 = client.responses.create(model="claude-sonnet-4-6", input="Jam berapa sekarang di Jakarta?", tools=tools, store=False)
call = next(o for o in r1.output if o.type == "function_call")

# Giliran berikutnya: kirim ulang riwayat + hasil tool (stateless)
r2 = client.responses.create(
    model="claude-sonnet-4-6",
    tools=tools,
    store=False,
    input=[
        {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "Jam berapa sekarang di Jakarta?"}]},
        *[o.model_dump(exclude_none=True) for o in r1.output],
        {"type": "function_call_output", "call_id": call.call_id, "output": '{"time": "10:00 WIB"}'},
    ],
)
print(r2.output_text)
```

## フォーマットエラー

```json theme={null}
{ "error": { "message": "API key tidak valid atau sudah dicabut.", "type": "authentication_error", "param": null, "code": "invalid_api_key" } }
```

| HTTP | `error.type` | `error.code` | 一般的な原因 |
| - | - | - | - |
| 400 | `invalid_request_error` | `invalid_request` | ボディが無効です。`max_output_tokens`がモデルの制限を超えています。`previous_response_id`が送信されました。Service Modeキーにはモデルが存在しません。 |
| 401 | `authentication_error` | `invalid_api_key` | APIキーが間違っている、無効化されている、または有効期限が切れている、あるいはAPIキーなしでリクエストが行われた。 |
| 402 | `insufficient_quota` | `insufficient_quota` | 残高が不足しているか、APIキーのクレジット上限に達しています。 |
| 403 | `permission_error` | - | アカウントが停止されました／アクセスが拒否されました。 |
| 404 | `not_found_error` | `model_not_found` / `not_found` | slugモデルが存在しない、または `GET /v1/responses/{id}`（ステートレス）。 |
| 429 | `rate_limit_error` | `rate_limit_exceeded` | リクエストの制限に達しました（ヘッダー `Retry-After` を参照）。 |
| 503 | `server_error` | `model_unavailable` / `server_error` | モデル/アップストリームが利用できません - 再試行しても問題ありません。 |

エラーメッセージには、アップストリームプロバイダーの識別子が含まれていません。Chat Completions 形式のエラーコードの完全な一覧は、[エラー](https://docs.hostlinku.com/ja/errors.md) に記載されています。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.