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

# API Reference

> Two protocols supported: OpenAI-compatible and Anthropic Claude — pick what fits

RuAPI supports **two API protocols simultaneously**: classic OpenAI-compatible and native Anthropic Claude-compatible. The same API key works with both.

<CardGroup cols={2}>
  <Card title="OpenAI protocol" icon="plug">
    `POST /v1/chat/completions` — industry standard, supported by virtually all SDKs and frameworks.
  </Card>

  <Card title="Claude protocol" icon="brain">
    `POST /v1/messages` — native Anthropic format with thinking blocks and MCP support.
  </Card>
</CardGroup>

**Quick reference:**

|             | OpenAI-compatible              | Anthropic                         |
| ----------- | ------------------------------ | --------------------------------- |
| `base_url`  | `https://www.ruapi.ai/v1`      | `https://www.ruapi.ai` (no `/v1`) |
| Endpoint    | `POST /v1/chat/completions`    | `POST /v1/messages`               |
| Auth header | `Authorization: Bearer sk-...` | `x-api-key: sk-...`               |

## Base URL

The address depends on the protocol — this is the #1 thing people get wrong:

**OpenAI-compatible** — with `/v1`:

```
https://www.ruapi.ai/v1
```

**Anthropic** — without `/v1` (the SDK appends `/v1/messages` itself):

```
https://www.ruapi.ai
```

The endpoint tables below show full paths from the domain root. Auth via the `Authorization: Bearer sk-...` header (`x-api-key` also works on `/v1/messages`).

<Warning>
  For Anthropic, **do not** add `/v1` to the `base_url` — an extra `/v1` returns a **404**.
</Warning>

***

## OpenAI protocol

Use this protocol if your code already uses the official **OpenAI SDK** or a compatible framework (LangChain, LlamaIndex, Vercel AI SDK, etc.).

### Endpoint

```
POST https://www.ruapi.ai/v1/chat/completions
```

### Compatibility

The request/response format matches [OpenAI's Chat Completions API](https://platform.openai.com/docs/api-reference/chat). Supported:

* `messages` (with roles `system` / `user` / `assistant` / `tool`)
* `model` — name of any model in the catalog (Claude/Gemini/Grok/Qwen/MiniMax/GLM included — we convert on the fly)
* `stream: true` for streaming responses (Server-Sent Events)
* `tools` / `tool_choice` for function calling
* `temperature`, `top_p`, `max_tokens` and other parameters

### Example: Python (OpenAI SDK)

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="sk-YOUR_KEY",
    base_url="https://www.ruapi.ai/v1",
)

response = client.chat.completions.create(
    model="claude-opus-4-8",  # see www.ruapi.ai for available models
    messages=[
        {"role": "system", "content": "You are a friendly assistant."},
        {"role": "user", "content": "Hello! What can you do?"},
    ],
    temperature=0.7,
)

print(response.choices[0].message.content)
print(f"Tokens used: {response.usage.total_tokens}")
```

### Example: Node.js (OpenAI SDK)

```javascript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-YOUR_KEY",
  baseURL: "https://www.ruapi.ai/v1",
});

const response = await client.chat.completions.create({
  model: "claude-opus-4-8", // see www.ruapi.ai for available models
  messages: [
    { role: "user", content: "Explain quantum entanglement simply." },
  ],
});

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

### Example: curl + streaming

```bash theme={null}
curl https://www.ruapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "Write a haiku about code."}],
    "stream": true
  }'
```

***

## Claude protocol

Use this protocol if your code is built on the **Anthropic SDK** or you need Claude-specific features (thinking blocks, native tool calls).

### Endpoint

```
POST https://www.ruapi.ai/v1/messages
```

### Compatibility

The request/response format matches [Anthropic's Messages API](https://docs.anthropic.com/claude/reference/messages_post). Supported:

* `messages` array (native Claude format)
* `system` as a separate field
* `model` — Claude model name or any other (we convert it into the Claude protocol)
* `max_tokens` (required for Claude)
* `stream: true`
* `tools` / `tool_choice`
* `thinking` for reasoning models

### Example: Python (Anthropic SDK)

```python theme={null}
from anthropic import Anthropic

client = Anthropic(
    api_key="sk-YOUR_KEY",
    base_url="https://www.ruapi.ai",
)

response = client.messages.create(
    model="claude-opus-4-8",  # see www.ruapi.ai for available models
    max_tokens=1024,
    system="You are a technical expert.",
    messages=[
        {"role": "user", "content": "What is the CAP theorem?"},
    ],
)

print(response.content[0].text)
print(f"Used: input={response.usage.input_tokens}, output={response.usage.output_tokens}")
```

### Example: Node.js (Anthropic SDK)

```javascript theme={null}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: "sk-YOUR_KEY",
  baseURL: "https://www.ruapi.ai",
});

const response = await client.messages.create({
  model: "claude-opus-4-8", // see www.ruapi.ai for available models
  max_tokens: 1024,
  messages: [
    { role: "user", content: "Explain Rust's borrow checker." },
  ],
});

console.log(response.content[0].text);
```

### Example: curl

```bash theme={null}
curl https://www.ruapi.ai/v1/messages \
  -H "x-api-key: sk-YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Write a haiku about code."}]
  }'
```

<Note>
  The Anthropic SDK uses the `x-api-key` header instead of `Authorization: Bearer`. RuAPI accepts both on the `/v1/messages` endpoint.
</Note>

***

## Which protocol should I pick?

| Scenario                                            | Use                              |
| --------------------------------------------------- | -------------------------------- |
| Already on OpenAI SDK / LangChain / LlamaIndex      | **OpenAI protocol**              |
| Writing native Anthropic code, need thinking blocks | **Claude protocol**              |
| Want to call Claude from existing OpenAI code       | **OpenAI protocol** (we convert) |
| Want to call gpt-5.4 from Anthropic SDK             | **Claude protocol** (we convert) |

In every case — **same API key**, same per-token price, shared balance.

## All endpoints

| Method | Path                       | Purpose                              |
| ------ | -------------------------- | ------------------------------------ |
| POST   | `/v1/chat/completions`     | OpenAI Chat Completions              |
| POST   | `/v1/messages`             | Claude Messages                      |
| POST   | `/v1/embeddings`           | Embeddings (OpenAI compatible)       |
| POST   | `/v1/images/generations`   | Image generation (OpenAI compatible) |
| POST   | `/v1/audio/transcriptions` | Whisper transcription                |
| POST   | `/v1/audio/speech`         | TTS — text to speech                 |
| GET    | `/v1/models`               | List of available models             |

The full list with current models lives on the **Pricing** page at [www.ruapi.ai](https://www.ruapi.ai).