OpenAI SDK Integration — Markdown source

> **AI Agents**: Index `/api/llms.txt` | Full EN `/api/llms-full-en.txt` | Full ZH `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# OpenAI SDK Integration

SupaNexus is a **drop-in replacement** for OpenAI's API when using official OpenAI SDKs. Change only `base_url` (or `baseURL`) and `api_key`.

## Configuration

| OpenAI default | SupaNexus value |
|----------------|-------------|
| `https://api.openai.com/v1` | `<BASE_URL>/v1` |
| OpenAI API key | SupaNexus project API key |

> Fill `<BASE_URL>` from [Endpoints](./endpoints.md).

## Python

```python
from openai import OpenAI

client = OpenAI(
    base_url="<BASE_URL>/v1",
    api_key="whale-project-api-key",
)

# Non-streaming
response = client.chat.completions.create(
    model="deepseek/deepseek-chat",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

# Streaming
with client.chat.completions.stream(
    model="deepseek/deepseek-chat",
    messages=[{"role": "user", "content": "Hello!"}],
) as stream:
    for event in stream:
        if event.type == "content.delta":
            print(event.delta, end="", flush=True)
```

### Environment variables

```bash
export OPENAI_API_KEY="whale-project-api-key"
export OPENAI_BASE_URL="<BASE_URL>/v1"
```

Many tools that read `OPENAI_*` env vars work without code changes.

## Node.js / TypeScript

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "<BASE_URL>/v1",
  apiKey: process.env.SNX_API_KEY,
});

const response = await client.chat.completions.create({
  model: "deepseek/deepseek-chat",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0]?.message?.content);
```

## LangChain

```python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="<BASE_URL>/v1",
    api_key="whale-project-api-key",
    model="deepseek/deepseek-chat",
)
```

## Differences from OpenAI

| Topic | SupaNexus behavior |
|-------|----------------|
| Model ids | Use the `id` from `GET /v1/models` (e.g. `vendor/model`), not OpenAI model names |
| Embeddings / Images | Routes exist but return **501** — not yet available |
| Extra headers | `X-SNX-Trace-ID`, `X-SNX-Model`, `X-SNX-Provider` on chat |
| Billing | Metered per organization/project; see console for usage |

## Roadmap (not available yet)

These endpoints are registered but return HTTP **501**:

- `POST /v1/embeddings`
- `POST /v1/images/generations`

Do not use them in production integrations until announced.

## Related

- [Quickstart](./quickstart.md)
- [Models](./models.md)
- [Streaming](./streaming.md)