Документация API

1. Быстрый старт

curl https://api.clavis.to/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

2. Аутентификация

Authorization: Bearer sk-your-api-key

https://api.clavis.to/v1

3. Модели

curl https://api.clavis.to/v1/models

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "owned_by": "OpenAI",
      "display_name": "gpt-4o",
      "billing_type": "per_token",
      "pricing": {
        "input_per_1m_rub": 43.75,
        "output_per_1m_rub": 131.25,
        "input_per_1m_cny": 2.5,
        "output_per_1m_cny": 7.5
      },
      "endpoints": ["openai"],
      "is_active": true
    }
  ]
}

4. Chat Completions

Основной эндпоинт для генерации ответов. Полностью совместим со спецификацией OpenAI Chat Completions API.

Параметры запроса

Роли сообщений

Пример запроса

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "Ты полезный ассистент."
    },
    {
      "role": "user",
      "content": "Объясни квантовые вычисления простыми словами"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 1000
}

5. Стриминг

curl

curl https://api.clavis.to/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}],"stream":true}'

Формат SSE-чанка

data: {"id":"req-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"req-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":"stop"}]}

data: [DONE]

Поток завершается сообщением data: [DONE]. Каждая строка данных — это JSON-объект с полем delta, содержащим сгенерированную часть ответа.

6. Формат ответа

{
  "id": "req-a1b2c3d4e5f6g7h8",
  "object": "chat.completion",
  "created": 1711234567,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Чем могу помочь?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}

Поля ответа

7. Обработка ошибок

API возвращает стандартные HTTP-коды ошибок. Тело ответа содержит объект error с описанием проблемы.

Формат ошибки

{
  "detail": "Недостаточно средств. Пожалуйста, пополните баланс."
}

8. Биллинг и тарификация

стоимость = (prompt_tokens × цена_ввода + completion_tokens × цена_вывода) / 1 000 000

9. Примеры на Python

Используя openai SDK (рекомендуется)

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.clavis.to/v1"
)

# Обычный запрос
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "Ты полезный ассистент"},
        {"role": "user", "content": "Что такое нейронные сети?"}
    ],
    temperature=0.7,
    max_tokens=1000
)

print(response.choices[0].message.content)
print(f"Токены: {response.usage.total_tokens}")
print(f"Модель: {response.model}")

Стриминг на Python

stream = client.chat.completions.create(
    model="claude-3.5-sonnet",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Используя httpx (без SDK)

import httpx

response = httpx.post(
    "https://api.clavis.to/v1/chat/completions",
    headers={"Authorization": "Bearer sk-your-key"},
    json={
        "model": "deepseek-v3",
        "messages": [{"role": "user", "content": "Hello!"}]
    },
    timeout=120.0
)

data = response.json()
print(data["choices"][0]["message"]["content"])

10. Примеры на JavaScript

fetch API

const response = await fetch("https://api.clavis.to/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-your-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello!" }],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

openai npm package

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-your-key",
  baseURL: "https://api.clavis.to/v1",
});

const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});

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

Стриминг на JavaScript

const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || "";
  process.stdout.write(content);
}

11. Лимиты и ограничения