# Claude メッセージを作成

**API:** Model API

**Endpoint:** `POST /api/v1/messages`

Claude Messages API 互換のエンドポイントです。stream=true を設定すると Claude 形式のメッセージストリームイベントを受信します。リクエスト、レスポンス、検証エラーのフィールドは Claude Messages プロトコルに従います。インフラ障害時には、Router がサニタイズされたゲートウェイエラーのエンベロープを返すこともあります。

## Base URL

- `https://openapi.felo.ai` — 本番環境

## Authentication

- `FeloBearerAuth` (http bearer) — Felo APIキーを `Authorization: Bearer <key>` として送信します。
- `FeloApiKey` (apiKey in header `X-API-Key`) — Felo APIキーを `X-API-Key: <key>` として送信します。

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Felo-Channel` | header | no | string, default: "default" | カンマ区切りの公開チャンネルコード（順序どおり）。このヘッダーを省略すると default が使われ、default は単独でのみ使用できます。ウォレットモードでは、default はモデルの有効な公開チャンネル順を逆から走査し、未公開または利用不可のチャンネルをスキップして、最初に利用可能なチャンネルのプロバイダーを選択します。そのプロバイダーから、同じ上流モデル ID とサービスティアを持つ利用可能なエンドポイントを含めます。明示的なチャンネルはクライアントが指定した順序で検証され、最初のチャンネルのプロバイダーグループのみが送信されます。他のプロバイダーへの自動フォールバックはありません。従来のプロバイダーヘッダーでチャンネルルーティングを上書きすることはできません。 |

## Request body

Required: **yes**

### application/json

Schema: `ClaudeMessagesRequest` (`#/components/schemas/ClaudeMessagesRequest`)

```json
{
  "type": "object",
  "required": [
    "model",
    "max_tokens",
    "messages"
  ],
  "properties": {
    "model": {
      "type": "string"
    },
    "max_tokens": {
      "type": "integer",
      "minimum": 1
    },
    "messages": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/components/schemas/ClaudeMessage"
      },
      "description": "Use a document block for a PDF or an image block for a picture. Set source to {type: 'file', file_id: 'felo_file_...'} for an uploaded Felo attachment, {type: 'url', url: 'https://...'} for an HTTPS URL, or provide type, media_type and data for a base64 source. PDF and image URL support are enabled per model."
    },
    "system": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        }
      ]
    },
    "stream": {
      "type": "boolean",
      "default": false
    },
    "temperature": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "top_p": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "top_k": {
      "type": "integer",
      "minimum": 0
    },
    "stop_sequences": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "tool_choice": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "additionalProperties": true
        }
      ]
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true
    },
    "thinking": {
      "type": "object",
      "additionalProperties": true
    },
    "service_tier": {
      "type": [
        "string",
        "null"
      ],
      "default": "default",
      "description": "現在は default（standard）のみをサポートしています。省略、null、エイリアス、未対応の文字列は default にフォールバックし、それ以外のタイプは HTTP 400 を返します。設定済みのチャンネルと料金は変わりません。テキスト API はプロバイダーの標準値を使用し、Decisions と生成 API は上流のフィールドを省略します。"
    }
  },
  "additionalProperties": true
}
```

Example:

```json
{
  "model": "claude-sonnet-4-5",
  "max_tokens": 256,
  "messages": [
    {
      "role": "user",
      "content": "Write a one-sentence greeting."
    }
  ],
  "stream": false
}
```

## Responses

### 200 — Claude メッセージ、またはストリーミングレスポンス

**application/json**

Schema: `ClaudeMessageResponse` (`#/components/schemas/ClaudeMessageResponse`)

**text/event-stream**

Schema: string

```json
{
  "type": "string",
  "description": "Claude Messages の SSE イベント。"
}
```

### 400 — Claude の invalid_request_error、または Router のリクエスト検証エラー

**application/json**

Schema: `ClaudeErrorResponse` (`#/components/schemas/ClaudeErrorResponse`)

### 401 — Felo APIキーが無効または未指定です

**application/json**

Schema: `ClaudeErrorResponse` (`#/components/schemas/ClaudeErrorResponse`)

### 402 — 残高不足

**application/json**

Schema: `ClaudeErrorResponse` (`#/components/schemas/ClaudeErrorResponse`)

### 403 — アカウントにこのモデルの使用権限がありません。無効化されたモデルも上流呼び出しの前に拒否されます。既に受け付けたリクエストとタスクは継続します。

**application/json**

Schema: `ClaudeErrorResponse` (`#/components/schemas/ClaudeErrorResponse`)

### 429 — 支出上限またはリクエスト上限に達しました

**application/json**

Schema: `ClaudeErrorResponse` (`#/components/schemas/ClaudeErrorResponse`)

### 502 — 上流プロバイダーへのリクエストに失敗しました

**application/json**

Schema: `ClaudeErrorResponse` (`#/components/schemas/ClaudeErrorResponse`)

### 503 — プロバイダーまたは請求サービスが利用できません

**application/json**

Schema: `ClaudeErrorResponse` (`#/components/schemas/ClaudeErrorResponse`)

## Schema definitions

### ClaudeContentBlock

`#/components/schemas/ClaudeContentBlock`

```json
{
  "type": "object",
  "required": [
    "type"
  ],
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "text",
        "image",
        "document",
        "tool_use",
        "tool_result",
        "thinking"
      ]
    },
    "text": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "input": {
      "type": "object",
      "additionalProperties": true
    },
    "content": {
      "type": [
        "string",
        "array"
      ]
    },
    "source": {
      "type": "object",
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}
```

### ClaudeErrorResponse

`#/components/schemas/ClaudeErrorResponse`

```json
{
  "type": "object",
  "description": "Messages リクエスト向けの、Claude Errors API 互換のエラーエンベロープ。",
  "required": [
    "type",
    "error"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "error"
    },
    "error": {
      "type": "object",
      "required": [
        "type",
        "message"
      ],
      "properties": {
        "type": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "request_id": {
      "type": "string"
    }
  },
  "additionalProperties": true
}
```

### ClaudeMessage

`#/components/schemas/ClaudeMessage`

```json
{
  "type": "object",
  "required": [
    "role",
    "content"
  ],
  "properties": {
    "role": {
      "type": "string",
      "enum": [
        "user",
        "assistant"
      ]
    },
    "content": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/ClaudeContentBlock"
          }
        }
      ]
    }
  },
  "additionalProperties": true
}
```

### ClaudeMessageResponse

`#/components/schemas/ClaudeMessageResponse`

```json
{
  "type": "object",
  "required": [
    "id",
    "type",
    "role",
    "content",
    "model",
    "stop_reason"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "const": "message"
    },
    "role": {
      "type": "string",
      "const": "assistant"
    },
    "content": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ClaudeContentBlock"
      }
    },
    "model": {
      "type": "string"
    },
    "stop_reason": {
      "type": [
        "string",
        "null"
      ]
    },
    "stop_sequence": {
      "type": [
        "string",
        "null"
      ]
    },
    "usage": {
      "$ref": "#/components/schemas/Usage"
    }
  },
  "additionalProperties": true
}
```

### Usage

`#/components/schemas/Usage`

```json
{
  "type": "object",
  "description": "プロバイダーの usage オブジェクト。フィールドはエンドポイントとプロバイダーによって異なります。",
  "additionalProperties": true
}
```
