API integration

Choose an AIXHUB protocol or Python SDK, use the correct URL level, and verify the first request in Usage.

Use this section when you are writing application or service code. If you are configuring an existing desktop or command-line tool, start with Client guides instead; each client composes URLs and stores credentials differently.

Prerequisites

Choose an integration

Goal	Protocol or library	Start here
Send raw OpenAI-compatible requests	OpenAI Responses	Responses API
Send raw Anthropic-compatible requests	Anthropic Messages	Messages API
Use the OpenAI Python package	OpenAI Responses through the SDK	OpenAI Python SDK
Use the Anthropic Python package	Anthropic Messages through the SDK	Anthropic Python SDK
Decide how to send the key	Bearer or `x-api-key`	Authentication and Base URL

Create a separate AIXHUB key for each application or service. Do not reuse a key from Codex, Claude Code, Cherry Studio, or another client.

Use the correct URL level

Value	Exact address	Use it when
AIXHUB origin	`https://api.aixhub.org`	An Anthropic SDK or client asks for a Base URL and appends `/v1/messages`
OpenAI-compatible Base URL	`https://api.aixhub.org/v1`	An OpenAI SDK or client appends a resource such as `/responses`
Responses endpoint	`https://api.aixhub.org/v1/responses`	Sending a raw Responses HTTP request
Messages endpoint	`https://api.aixhub.org/v1/messages`	Sending a raw Anthropic Messages HTTP request

A Base URL is not a complete endpoint. Match the field label and the selected protocol before pasting a value. Never create /v1/v1, and do not put /responses or /messages into a field that already appends the resource path.

Steps

Create a dedicated API key.
Copy the exact compatible model ID from Model routes. The examples use panel-model-id as a visible stand-in.
Follow Authentication and Base URL to run one minimal request from Bash or PowerShell.
Keep the first input deterministic and tool-free: Reply with OK only.
Read the complete response or terminal stream event before treating the call as successful.
Open Usage and match the request time, model, status, and, when shown, protocol.

Verification

Expected application output:

OK

The visible text alone does not prove which route handled the call. The local response and the AIXHUB Usage record must agree.

Troubleshooting

Production checklist

Keep keys in a server-side secret store or protected environment, never in public browser code.
Set connection and read timeouts appropriate for generation requests.
Log the request time, selected model, HTTP status, and request ID when one is returned; never log authorization headers or complete prompts by default.
Honor Retry-After and cap retries. Correct 400, 401, 403, and 413 responses before retrying instead of replaying them unchanged.
Treat streaming success as a terminal success event, not merely the initial HTTP 200 status.
Check Usage before replaying an interrupted generation so a network error does not create duplicate work or charges.

For failure envelopes and retry boundaries, use the error code reference.

Next step

Official sources

Last verified: 2026-07-14

API integration

On this page