Xpersona developer documentation

Quick start#

Call your first model in under three minutes.

1. Create a Xpersona account and generate an API key in the Connect AI dashboard.
2. Pick any model ID from the model catalog.
3. Point your OpenAI-compatible client at https://www.xpersona.co/v1 and send a request.

Chat completion

curl https://www.xpersona.co/v1/chat/completions \
  -H "Authorization: Bearer $XPERSONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-fable-5",
    "messages": [
      {"role": "user", "content": "What is the meaning of life?"}
    ]
  }'

Native OpenCode setup#

Xpersona is a first-party OpenCode provider. Choose xpersona from the provider picker, then run the generated setup script with your key. The default OpenCode model is xpersona/claude-fable-5 (Claude Fable 5, 1M context).

export XPERSONA_API_KEY='xp_your_key'
opencode models xpersona --refresh --verbose
opencode run -m xpersona/claude-fable-5 "Reply with exactly: XPERSONA_OK"
opencode

Full guide: /opencode. Verify discovery with curl https://www.xpersona.co/v1/models.

Authentication#

All authenticated endpoints use a bearer key created in the dashboard. Keys are shown once — store them in a secret manager or environment variable.

1. Sign in and open Dashboard → Connect AI.
2. Create a key (prefix xp_) and copy it immediately.
3. Export it as XPERSONA_API_KEY and send it on every request.

Base URL & protocol#

One gateway serves the whole catalog. The production base URL is https://www.xpersona.co/v1, and the four core routes mirror the OpenAI surface you already know:

Model catalog#

Popular models and their retail rates. Prices are USD per one million tokens; cached input applies when a provider cache hit occurs on supported routes.

Full catalog with filters and live pricing: /models. Machine-readable: GET https://www.xpersona.co/v1/models and GET https://www.xpersona.co/v1/pricing.

Streaming#

Set "stream": true to receive server-sent events. Each chunk carries a partial delta; the stream ends with a [DONE] sentinel, exactly like the OpenAI wire format.

curl https://www.xpersona.co/v1/chat/completions \
  -H "Authorization: Bearer $XPERSONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-fable-5",
    "stream": true,
    "messages": [{"role": "user", "content": "Count to five"}]
  }'

Function calling#

Pass a tools array to let the model request structured tool calls. Execute the tool server-side, then append the result as a tool message and continue the conversation.

from openai import OpenAI

client = OpenAI(base_url="https://www.xpersona.co/v1", api_key="$XPERSONA_API_KEY")

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="claude-fable-5",
    messages=[{"role": "user", "content": "Weather in Tokyo?"}],
    tools=tools,
)

print(response.choices[0].message.tool_calls[0].function.arguments)

Vision input#

Vision-capable models accept image parts alongside text. Supply a public HTTPS URL or a base64 data URL in the content array. Check the catalog capabilities before sending images.

curl https://www.xpersona.co/v1/chat/completions \
  -H "Authorization: Bearer $XPERSONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-fable-5",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "What is in this image?"},
          {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
        ]
      }
    ]
  }'

Structured outputs#

Constrain responses to a JSON Schema with response_format. With strict: true the model must return valid JSON that matches your schema — ideal for extraction pipelines and agent planners.

from openai import OpenAI

client = OpenAI(base_url="https://www.xpersona.co/v1", api_key="$XPERSONA_API_KEY")

response = client.chat.completions.create(
    model="claude-fable-5",
    messages=[{"role": "user", "content": "Invoice from Acme, $120 due June 1"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "invoice",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "vendor": {"type": "string"},
                    "amount_usd": {"type": "number"},
                    "due_date": {"type": "string"},
                },
                "required": ["vendor", "amount_usd", "due_date"],
                "additionalProperties": False,
            },
        },
    },
)

print(response.choices[0].message.content)

Prompt caching#

Repeated prefixes (system prompts, retrieved documents, long tool definitions) are automatically cached on managed routes. Cache hits are billed at roughly 10% of the uncached input rate, so stable prompt prefixes materially cut cost and latency. Cached prices appear in the catalog and in GET https://www.xpersona.co/v1/pricing.

Error handling#

Errors return standard HTTP status codes with an OpenAI-style body:

{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Retry 500/502 once with backoff, honor 429, and treat 402 as a billing signal rather than an error to retry blindly.

Billing & packages#

Access the full catalog with a fixed monthly package, or pay as you go with prepaid credits from $2. Package requests pause at the monthly compute allowance instead of creating overage charges; prepaid usage pauses at a zero balance. Stripe handles checkout.

Compare plans on /pricing; manage payment methods and invoices in Dashboard → Billing.

Usage & dashboard#

Pull your own telemetry programmatically, or read it visually in the dashboard:

curl https://www.xpersona.co/v1/usage \
  -H "Authorization: Bearer $XPERSONA_API_KEY"

• Prepaid credit state, API key prefix, and plan status
• Monthly spend, weekly usage, and token totals per model
• Latency and a log of recent requests
• Retail price card for reconciliation against /v1/pricing

Council multi-model runs#

Run one task across several frontier models, blind-judge the evidence, and continue with the winner. Council sessions are created by signed-in users via POST /v1/council, and each session can produce a shareable proof receipt (GET /v1/council/:id/receipt, private by default).

Full guide: /docs/council. Product surface: /council.

Agent discovery flow#

The recommended flow for autonomous clients evaluating third-party agents:

• Discover — start from feed views: latest, benchmarked, security-reviewed, openapi-ready.
• Inspect evidence — read snapshot, contract, trust, card, and facts before acting.
• Act — recommend, crawl, or route work; use /v1 inference once your user has an active plan.

Retired search endpoints intentionally return 410 — crawlers should move to the feed-first flow above.

Endpoint reference#

Machine-readable surfaces#

Built for autonomous clients, crawlers, and LLM framework adapters: