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

# Chat Completion

> Unified streaming chat across inference providers

Runs a chat completion against the provider encoded in the model id. Dolphin
models are free. Paid providers may return a standard x402 challenge; payment
mechanics remain provider-specific behind this one endpoint.

## Headers

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

<ParamField header="PAYMENT-SIGNATURE" type="string">
  Base64-encoded signed x402 payload. Omit on the first request. When the
  selected provider returns `402`, sign one accepted offer and retry the same
  body with this header.
</ParamField>

## Body

<ParamField body="messages" type="array" required>
  Non-empty conversation history as `{(role, content)}` objects.
</ParamField>

<ParamField body="model" type="string" default="dolphinserver:24B">
  Namespaced `provider/model` id from [`GET
          /v1/inference/models`](/api-reference/inference/models). Unprefixed ids remain
  Dolphin for backward compatibility.
</ParamField>

<ParamField body="template" type="string" default="logical">
  Dolphin-only prompt template. Supplying it for another provider returns `400`.
  Fetch valid values from [`GET
          /v1/inference/templates`](/api-reference/inference/templates).
</ParamField>

## Response

Success is streamed as `text/event-stream`. Concatenate
`choices[0].delta.content`; the stream ends with `data: [DONE]`. Paid
providers return settlement metadata in `PAYMENT-RESPONSE`.

<RequestExample>
  ```bash Free Dolphin theme={"system"} theme={null}
  curl -N -X POST https://pearl.computer/v1/inference/chat \
    -H "Content-Type: application/json" \
    -d '{
      "messages": [{ "role": "user", "content": "hey" }],
      "model": "dolphin/dolphinserver:24B",
      "template": "logical"
    }'
  ```

  ```bash Paid provider: first request obtains the challenge theme={"system"} theme={null}
  curl -i -X POST https://pearl.computer/v1/inference/chat \
    -H "Content-Type: application/json" \
    -d '{
      "messages": [{ "role": "user", "content": "hey" }],
      "model": "surplus/zai-org/glm-4.5",
      "stream": true
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 402 Payment Required theme={"system"} theme={null}
  {
    "x402Version": 2,
    "resource": {
      "url": "https://pearl.computer/v1/inference/chat"
    },
    "accepts": [
      {
        "scheme": "exact",
        "network": "eip155:8453",
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "amount": "12000",
        "payTo": "0x...",
        "extra": { "name": "USD Coin", "version": "2" }
      }
    ]
  }
  ```

  ```text 200 OK (SSE stream) theme={"system"} theme={null}
  data: {"choices":[{"delta":{"content":"Hey"}}]}

  data: {"choices":[{"delta":{"content":" there!"}}]}

  data: [DONE]
  ```

  ```json 400 Bad Request theme={"system"} theme={null}
  {
    "error": "Unknown model \"nosuch/model\"",
    "supported": ["dolphin/dolphinserver:24B", "surplus/zai-org/glm-4.5"],
    "supportedTruncated": 312
  }
  ```
</ResponseExample>


## OpenAPI

````yaml api-reference/inference/openapi.json POST /v1/inference/chat
openapi: 3.1.0
info:
  title: Pearl Inference API
  description: OpenAI-compatible inference router with x402, prepaid, and durable media.
  version: 1.0.0
servers:
  - url: https://pearl.computer
security: []
tags:
  - name: Inference
    description: Chat, catalog, providers, and templates
paths:
  /v1/inference/chat:
    post:
      tags:
        - Inference
      summary: Chat Completion
      description: Unified streaming chat across inference providers.
      operationId: inferenceChat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - messages
              properties:
                messages:
                  type: array
                  items:
                    type: object
                model:
                  type: string
                template:
                  type: string
                stream:
                  type: boolean
      responses:
        '200':
          description: SSE stream or JSON completion
        '402':
          description: x402 payment required

````

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