Connect an API client to SoAI

Point an OpenAI-compatible client at one SoAI base URL, choose a model ID from SoAI's catalog, and use a SoAI API key when the instance requires one. This connection is for inference. It does not grant a WebUI session, shell access, administrator access, or MCP access.

Prepare the server

1. Complete the first-run setup wizard. Compatible API routes are unavailable before the first user exists.
2. In the SoAI WebUI, open Models and confirm that the intended model is available. Copy the exact model ID rather than the display label.
3. For a client outside the host, configure the private listening address and TLS first. See Network and TLS.
4. If authentication should be required, select the Settings button at the right of the header, choose Settings, and open OpenAI. This tab appears only to an Administrator with API key management (OPENAI_API_ADMIN). Select Create key and copy the key when it is shown.

After setup, /v1/* remains open while the API-key store has no records. Creating the first key makes authentication mandatory. Revoking or expiring the last usable key does not reopen the API because the key records still exist. See Authentication and API keys before changing that state.

Configure and test the client

Most OpenAI-compatible clients expect a base URL ending in /v1:

http://127.0.0.1:5090/v1

Replace the scheme, host, and port with the values printed by your launcher or configured for the deployment. Some clients ask for a server origin and append /v1 themselves. Check the final request URL when you see a duplicated /v1/v1 or a 404 response.

Verify model discovery

curl http://127.0.0.1:5090/v1/models \
  -H "Authorization: Bearer YOUR_SOAI_API_KEY"

When the server has no API-key records, omit the authorization header. Choose an id returned by this endpoint. A virtual model uses its virtual name as that ID.

Send a chat request

curl http://127.0.0.1:5090/v1/chat/completions \
  -H "Authorization: Bearer YOUR_SOAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "Reply with one sentence."}]
  }'

Add "stream": true for OpenAI-format Server-Sent Events. SoAI emits data: {...} frames and finishes with data: [DONE]. The compatible stream is not a WebSocket and does not use SoAI WebUI event envelopes.

Choose the endpoint your client needs

Diagnose the first connection

• 401 or 403: verify the bearer value, key state and quota, and the instance's authentication state.
• 404: inspect the final URL for a missing or duplicated /v1.
• Model not found: copy the current ID from GET /v1/models and confirm the model is available.
• TLS error: trust the deployment's certificate authority. Do not disable certificate verification.
• Stream arrives all at once: disable response buffering in the private reverse proxy.

Related documentation

• Virtual models, routing, and failover
• Security hardening
• Connect coding agents to SoAI