# API リファレンス

LLM Gateway は OpenAI / Anthropic 互換の LLM 呼び出しエンドポイントを提供します（SaaS版のみ）。リクエスト / レスポンスは各社のネイティブ形式に準拠するため、既存の OpenAI SDK / Anthropic SDK をそのまま利用できます。

## ベース URL

OpenAI 系

`https://api.fd.agenticstar.tm.softbank.jp/llm/v1`

Anthropic 系

`https://api.fd.agenticstar.tm.softbank.jp/llm`

## 認証

| 方式                  | ヘッダー                                   |
| ------------------- | -------------------------------------- |
| API キー（OpenAI 系）    | Authorization: Bearer agtstr\_...      |
| API キー（Anthropic 系） | x-api-key: agtstr\_...                 |
| アクセストークン（CC フロー）    | Authorization: Bearer \<access\_token> |

API キー・クライアントの作成方法は [セットアップガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/llm-gateway/guide/setup.md) を参照してください。

## 共通仕様

- リクエストボディに `model` は必須です。利用可能なモデルは `GET /v1/models` で取得します。
- リクエストボディの上限は 32MB です。
- IP 制限が設定されている場合、許可外のネットワークからのリクエストは `403` になります。

## CORS

LLM Gateway はサーバーサイドからの利用を前提としており、**ブラウザからの直接呼び出し（クロスオリジン）は既定で許可されていません**。`Origin` を伴うブラウザリクエストは、オプトインヘッダが無い場合ブロックされます（サーバー間通信では `Origin` が付かないため影響ありません）。

ブラウザから直接呼び出す場合は、次のいずれかのヘッダを付与するとクロスオリジンが許可されます（`Access-Control-Allow-Origin: *` が返ります）。

| ヘッダー                                            | 説明                            |
| ----------------------------------------------- | ----------------------------- |
| anthropic-dangerous-direct-browser-access: true | Anthropic SDK のブラウザ直接呼び出しフラグ。 |
| x-agenticstar-allow-browser-access: true        | 同等の独自ヘッダー。                    |

> **警告**
>
> ブラウザから直接呼び出すと API キーがクライアントに露出します。API キーはサーバーサイドで管理し、ブラウザからの直接呼び出しは信頼できる用途に限定してください。

## エンドポイント一覧

| メソッド | パス                             | 互換        | 説明            |
| ---- | ------------------------------ | --------- | ------------- |
| POST | /llm/v1/chat/completions       | OpenAI    | チャット補完        |
| POST | /llm/v1/responses              | OpenAI    | Responses API |
| POST | /llm/v1/embeddings             | OpenAI    | 埋め込みベクトル生成    |
| GET  | /llm/v1/models                 | OpenAI    | 利用可能なモデル一覧    |
| POST | /llm/v1/messages               | Anthropic | メッセージ生成       |
| POST | /llm/v1/messages/count\_tokens | Anthropic | トークン数の計算      |

各エンドポイントのリクエスト / レスポンスの詳細は、OpenAI / Anthropic の公式仕様に準拠します。

- OpenAI 互換: [OpenAI API リファレンス](https://platform.openai.com/docs/api-reference)
- Anthropic 互換: [Anthropic API リファレンス](https://docs.anthropic.com/en/api)

## リクエスト例

各エンドポイントのリクエスト / レスポンス仕様は OpenAI / Anthropic 公式に準拠します。ここでは代表的な呼び出し例を示します。

### OpenAI 系

### POST`/llm/v1/chat/completions`

**Chat completion**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/llm/v1/chat/completions \
-H "Authorization: Bearer agtstr_..." \
-H "Content-Type: application/json" \
-d '{
  "model": "<モデル ID>",
  "messages": [{"role": "user", "content": "こんにちは"}]
}'
```

### Anthropic 系

### POST`/llm/v1/messages`

**Create a message**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/llm/v1/messages \
-H "x-api-key: agtstr_..." \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
  "model": "<モデル ID>",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "こんにちは"}]
}'
```

## ストリーミング

リクエストボディで `"stream": true` を指定すると、レスポンスを SSE（Server-Sent Events）で逐次受信できます。フォーマットは各系統のネイティブなストリーミング形式に準拠します。

**OpenAI 系** — `data: {チャンク}` 行が送られ、`data: [DONE]` で終了します。

```text
data: {"choices":[{"delta":{"content":"こん"}}]}

data: {"choices":[{"delta":{"content":"にちは"}}]}

data: [DONE]
```

**Anthropic 系** — `event:` と `data:` の組で配信されます（`message_start` → `content_block_delta` … → `message_stop`）。

```text
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"こん"}}

event: message_stop
data: {"type":"message_stop"}
```

## エラーレスポンス

エラー時に返される可能性のある主な HTTP ステータスコードです。

| ステータス                     | 説明                                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`         | リクエストが不正（`model` 欠落・JSON 不正・指定モデルが利用不可・コンテンツフィルタによるブロック等）                                                     |
| `401 Unauthorized`        | API キー / アクセストークンが無効または未指定                                                                                    |
| `403 Forbidden`           | IP 制限により許可されていないネットワークからのアクセス、ライセンス / 利用権限が有効でない場合、またはリクエストが前段のセキュリティの検査に止められた場合（参照番号がある場合は `message` に含まれます） |
| `404 Not Found`           | 存在しないパスへのリクエスト、または上流プロバイダが 404 を返した場合（利用できないモデルの指定は `400`）                                                    |
| `413 Payload Too Large`   | リクエストボディが 32MB を超過                                                                                            |
| `429 Too Many Requests`   | レート制限または上限超過。日次予算などのハード上限では `x-should-retry: false` が付与されます。rpm のレート制限では `Retry-After: 60` が付きます              |
| `501 Not Implemented`     | 該当エンドポイントが対象プロバイダで未対応（例: Responses API）                                                                       |
| `502 Bad Gateway`         | 上流プロバイダとの通信エラー等                                                                                               |
| `503 Service Unavailable` | 認証の仕組みが一時的に使えない。少し待ってから送り直してください。続くときは、サービスの管理者に問い合わせてください                                                    |

### エラーレスポンス形式

エラーボディは、呼び出したエンドポイントの系統のネイティブなエラー形式で返されます。

**OpenAI 系**

```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required parameter: model.",
    "code": "missing_model"
  }
}
```

**Anthropic 系**

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required parameter: model."
  }
}
```

## 利用ログ

利用状況（モデル・トークン数・コスト・レイテンシ等）は [システム連携 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/admin-api-reference.md) の `llm-gateway-logs` エンドポイント、または管理コンソールで確認できます。
