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

# メッセージを作成

> `/v1/messages` の Anthropic 互換 Messages エンドポイントです。

`/v1/messages` は Anthropic Messages API のリクエスト形式を受け取り、Anthropic 形式の応答を返します。

## ストリーミング

`stream: true` を設定すると、Anthropic 形式の Server-Sent Events（`message_start`、`content_block_*`、`message_delta`、`message_stop`）を受信できます。

## 補足

* Anthropic のツール使用フィールドに対応しています。
* `stream: true` はツールループでも利用できます。Gateway 管理サーバーツールでは、Phaseo が上流のターンを処理してループを続行し、合成ストリームを再送する場合があります。
* Anthropic ネイティブの Web 検索ツール形式も `tools` で直接指定できます。例: `type: "web_search_20250305"`。
* `X-Phaseo-Strictness` ヘッダーで、未対応パラメーターの扱いを制御します。

## サーバーツール

`/v1/messages` は次の Gateway 管理サーバーツールにも対応しています。

* `gateway:datetime`
* `phaseo:web_search`
* `phaseo:web_fetch`
* `phaseo:advisor`
* `phaseo:image_generation`

Phaseo はこれらのツールを上流プロバイダー向けの Anthropic 互換形式に変換してサーバー側で実行し、ツールループを続行します。

## プロバイダーのネイティブ Web 検索

互換性のある Anthropic モデルとプロバイダーの組み合わせがネイティブ Web 検索に対応している場合は、ネイティブのツール定義を直接渡すこともできます。

```bash theme={null}
curl https://api.phaseo.app/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "max_tokens": 512,
    "messages": [
      { "role": "user", "content": "Find the latest Anthropic web search guidance." }
    ],
    "tools": [
      {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 3,
        "allowed_domains": ["docs.anthropic.com"]
      }
    ],
    "tool_choice": { "type": "tool", "name": "web_search" }
  }'
```

実行前に、プロバイダーのルーティングで `web_search_options` の対応状況が引き続き確認されます。

### 日時の例

```bash theme={null}
curl https://api.phaseo.app/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "max_tokens": 512,
    "stream": false,
    "messages": [
      { "role": "user", "content": "What time is it in America/New_York right now?" }
    ],
    "tools": [
      {
        "type": "gateway:datetime",
        "parameters": { "timezone": "America/New_York" }
      }
    ],
    "tool_choice": { "type": "auto" }
  }'
```

使用すると、`usage.server_tool_use.*` カウンターにサーバーツールの呼び出し回数が記録されます。


## OpenAPI

````yaml ja/openapi/v1/openapi.localized.yaml POST /messages
openapi: 3.0.3
info:
  title: Phaseo Gateway API
  description: OpenAI互換のエンドポイントを通じて、さまざまなAIモデルにアクセスするためのゲートウェイAPI。
  version: 1.0.0
  contact:
    name: Phaseo
    url: https://phaseo.app
    email: danielbutler500@gmail.com
servers:
  - url: https://api.phaseo.app/v1
    description: グローバルルーティング
security:
  - BearerAuth: []
tags:
  - name: Gateway
    description: Core Phaseo Gateway operations.
paths:
  /messages:
    post:
      tags:
        - Gateway
      summary: メッセージを作成
      description: Anthropic Messages API を使用してメッセージを作成します。
      operationId: createAnthropicMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnthropicMessagesRequest'
            examples:
              datetimeServerTool:
                summary: Built-in datetime server tool
                value:
                  model: anthropic/claude-sonnet-4
                  max_tokens: 512
                  stream: false
                  messages:
                    - role: user
                      content: What time is it in America/New_York right now?
                  tools:
                    - type: gateway:datetime
                      parameters:
                        timezone: America/New_York
                  tool_choice:
                    type: auto
      responses:
        '200':
          description: メッセージの応答
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnthropicMessagesResponse'
            text/event-stream:
              schema:
                type: string
      servers:
        - url: https://api.phaseo.app/v1
          description: グローバルルーティング
        - url: https://eu.api.phaseo.app/v1
          description: EU 域内のプロバイダールーティング（テキストのみ）
        - url: https://us.api.phaseo.app/v1
          description: 米国内のプロバイダールーティング（テキストのみ）
components:
  schemas:
    AnthropicMessagesRequest:
      type: object
      required:
        - model
        - messages
        - max_tokens
      properties:
        model:
          type: string
        system:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - text
                  text:
                    type: string
                  cache_control:
                    $ref: '#/components/schemas/CacheControl'
        messages:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AnthropicMessage'
        max_tokens:
          type: integer
          minimum: 1
        service_tier:
          type: string
          description: 対応するテキスト API で、サポートされるルーティングまたは料金のティアを選択します。
          enum:
            - standard
            - default
            - fast
            - ultrafast
            - priority
            - flex
            - batch
        temperature:
          type: number
          minimum: 0
          maximum: 1
        top_p:
          type: number
          minimum: 0
          maximum: 1
        top_k:
          type: integer
          minimum: 1
        tools:
          type: array
          description: Anthropic 互換ツールと、ゲートウェイ管理のサーバーツールです。
          items:
            oneOf:
              - $ref: '#/components/schemas/AnthropicTool'
              - $ref: '#/components/schemas/GatewayDatetimeToolDefinition'
              - $ref: '#/components/schemas/GatewayWebSearchToolDefinition'
              - $ref: '#/components/schemas/GatewayWebFetchToolDefinition'
              - $ref: '#/components/schemas/SubagentToolDefinition'
              - $ref: '#/components/schemas/FusionToolDefinition'
              - $ref: '#/components/schemas/SearchModelsToolDefinition'
        tool_choice:
          description: >-
            Anthropic
            のツール選択オブジェクトまたは文字列です。ゲートウェイ管理のサーバーツール名も受け付け、ゲートウェイによって書き換えられます。
          oneOf:
            - type: object
            - type: string
        stream:
          type: boolean
        metadata:
          type: object
          additionalProperties: true
        session_id:
          type: string
          maxLength: 256
          description: 関連するリクエスト（会話やエージェントのワークフローなど）を可観測性のためにまとめる一意の識別子です。
        reasoning:
          $ref: '#/components/schemas/ReasoningConfig'
        stop_sequences:
          type: array
          items:
            type: string
        provider_options:
          $ref: '#/components/schemas/ProviderOptions'
        usage:
          type: boolean
        meta:
          type: boolean
        echo_upstream_request:
          type: boolean
        debug:
          $ref: '#/components/schemas/DebugOptions'
        provider:
          $ref: '#/components/schemas/ProviderRoutingOptions'
    AnthropicMessagesResponse:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        role:
          type: string
          enum:
            - assistant
        model:
          type: string
        content:
          type: array
          items:
            $ref: '#/components/schemas/AnthropicContentBlock'
        stop_reason:
          type: string
        stop_sequence:
          type: string
        usage:
          $ref: '#/components/schemas/AnthropicUsage'
    CacheControl:
      type: object
      properties:
        type:
          type: string
        ttl:
          type: string
        scope:
          type: string
      additionalProperties: true
    AnthropicMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/AnthropicContentBlock'
    AnthropicTool:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        async:
          type: boolean
          description: >-
            呼び出し元がこのツールを実行する間、対応する OpenAI
            モデルの処理を継続させます。他のプロバイダーにルーティングされた場合は無視されます。
        description:
          type: string
        input_schema:
          type: object
    GatewayDatetimeToolDefinition:
      type: object
      description: ゲートウェイ管理のサーバーツールです。ゲートウェイが日時を照会し、その結果をモデルのツールループに戻します。
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - phaseo:datetime
            - gateway:datetime
        parameters:
          type: object
          properties:
            timezone:
              type: string
              description: 'IANA タイムゾーン名（例: Europe/London）。'
          additionalProperties: false
        timezone:
          type: string
          description: 既定のタイムゾーン（IANA）を指定する旧形式のショートカットです。
      additionalProperties: false
    GatewayWebSearchToolDefinition:
      type: object
      description: ゲートウェイ管理のサーバーツールです。ゲートウェイが Web 検索を実行し、正規化した検索結果をモデルのツールループに戻します。
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - phaseo:web_search
            - gateway:web_search
        parameters:
          type: object
          properties:
            engine:
              type: string
              enum:
                - auto
                - native
                - exa
                - firecrawl
                - parallel
                - perplexity
                - tinyfish
            max_results:
              type: integer
              minimum: 1
              maximum: 25
            language:
              type: string
            page:
              type: integer
              minimum: 0
              maximum: 10
            include_text:
              type: boolean
            include_highlights:
              type: boolean
          additionalProperties: false
        max_results:
          type: integer
          minimum: 1
          maximum: 25
        engine:
          type: string
          enum:
            - auto
            - native
            - exa
            - firecrawl
            - parallel
            - perplexity
            - tinyfish
        language:
          type: string
        page:
          type: integer
          minimum: 0
          maximum: 10
        include_text:
          type: boolean
        include_highlights:
          type: boolean
      additionalProperties: false
    GatewayWebFetchToolDefinition:
      type: object
      description: >-
        ゲートウェイ管理のサーバーツールです。ゲートウェイが HTTP(S) ページを 1
        件取得してテキスト量を制限し、その結果をモデルのツールループに戻します。
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - phaseo:web_fetch
            - gateway:web_fetch
        parameters:
          type: object
          properties:
            max_chars:
              type: integer
              minimum: 1
              maximum: 100000
          additionalProperties: false
        max_chars:
          type: integer
          minimum: 1
          maximum: 100000
      additionalProperties: false
    SubagentToolDefinition:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - phaseo:subagent
        parameters:
          type: object
          additionalProperties: true
    FusionToolDefinition:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - phaseo:fusion
        parameters:
          type: object
          required:
            - analysis_models
          properties:
            analysis_models:
              type: array
              minItems: 2
              maxItems: 8
              items:
                type: string
            model:
              type: string
          additionalProperties: true
    SearchModelsToolDefinition:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - phaseo:search_models
        parameters:
          type: object
          properties:
            max_results:
              type: integer
              minimum: 1
              maximum: 20
    ReasoningConfig:
      type: object
      properties:
        effort:
          type: string
          enum:
            - none
            - minimal
            - low
            - medium
            - high
            - xhigh
            - max
          default: medium
        mode:
          type: string
          enum:
            - standard
            - pro
        summary:
          type: string
          enum:
            - auto
            - concise
            - detailed
          default: auto
        enabled:
          type: boolean
        max_tokens:
          type: integer
          minimum: 0
    ProviderOptions:
      type: object
      description: 任意のプロバイダー固有オプションです。
      properties:
        openai:
          type: object
          properties:
            context_management:
              type: object
              description: 任意の OpenAI コンテキスト管理設定です。
              properties:
                type:
                  type: string
                  enum:
                    - compaction
                compact_threshold:
                  type: number
              required:
                - type
            prompt_cache_retention:
              type: string
        anthropic:
          type: object
          properties:
            cache_control:
              $ref: '#/components/schemas/CacheControl'
        google:
          type: object
          properties:
            cache_control:
              $ref: '#/components/schemas/CacheControl'
            cached_content:
              type: string
            cache_ttl:
              type: string
    DebugOptions:
      type: object
      description: ゲートウェイのデバッグ設定です。これらのフラグがプロバイダーに転送されることはありません。
      properties:
        enabled:
          type: boolean
        return_upstream_request:
          type: boolean
        return_upstream_response:
          type: boolean
        trace:
          type: boolean
        trace_level:
          type: string
          enum:
            - summary
            - full
    ProviderRoutingOptions:
      type: object
      description: ゲートウェイでの選択に使用するプロバイダーのルーティング設定。
      properties:
        order:
          type: array
          items:
            type: string
        only:
          type: array
          items:
            type: string
        ignore:
          type: array
          items:
            type: string
        include_alpha:
          type: boolean
          description: ルーティングに alpha プロバイダーを含める（既定ではオフ）。
        allow_fallbacks:
          type: boolean
          nullable: true
          description: 失敗後に別の対象プロバイダーへフォールバックすることを許可します。
        require_parameters:
          type: boolean
          nullable: true
          description: ルーティング前に、要求されたパラメーターにプロバイダーが対応していることを必須にします。
        required_execution_region:
          type: string
          nullable: true
          description: 指定された実行リージョンに対応するプロバイダーにルーティングを限定します。
        required_data_region:
          type: string
          nullable: true
          description: 指定されたデータリージョンに対応するプロバイダーにルーティングを限定します。
        require_zero_data_retention:
          type: boolean
          nullable: true
          description: ゼロデータ保持に対応するプロバイダーにルーティングを限定します。
        data_collection:
          type: string
          nullable: true
          enum:
            - allow
            - deny
        zdr:
          type: boolean
          nullable: true
        enforce_distillable_text:
          type: boolean
          nullable: true
        quantizations:
          type: array
          nullable: true
          items:
            type: string
        sort:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          description: このリクエストのプロバイダーを、価格、レイテンシ、スループットなどで並べ替えます。
        max_price:
          type: object
          properties:
            prompt:
              oneOf:
                - type: number
                - type: string
            completion:
              oneOf:
                - type: number
                - type: string
            image:
              oneOf:
                - type: number
                - type: string
            audio:
              oneOf:
                - type: number
                - type: string
            request:
              oneOf:
                - type: number
                - type: string
        preferred_min_throughput:
          oneOf:
            - type: number
            - type: object
              additionalProperties:
                type: number
        preferred_max_latency:
          oneOf:
            - type: number
            - type: object
              additionalProperties:
                type: number
    AnthropicContentBlock:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
            - image
            - tool_use
            - tool_result
        text:
          type: string
        cache_control:
          $ref: '#/components/schemas/CacheControl'
        source:
          type: object
          properties:
            type:
              type: string
            media_type:
              type: string
            data:
              type: string
            url:
              type: string
        id:
          type: string
        name:
          type: string
        input:
          type: object
        tool_use_id:
          type: string
        content:
          type: string
    AnthropicUsage:
      type: object
      properties:
        input_tokens:
          type: integer
        output_tokens:
          type: integer
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer トークンによる認証

````

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