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

API Reference

ProxAI полностью совместим с OpenAI API — те же endpoint-ы, те же параметры.

Подключение клиента

Для работы нужны только два параметра: Base URL и API Key.

Base URL
https://proxai.ru/v1
API Key

Зарегистрируйтесь, чтобы создать API-ключ — скопировать его можно в любой момент в разделе «API Ключи».

Как настроить в популярных инструментах

Cursor Settings → Models → OpenAI API Key + Base URL Override
Cline Settings → API Provider → "OpenAI Compatible" → Base URL + API Key
Continue.dev config.json → provider: "openai" → apiBase + apiKey
OpenClaw openclaw.json → models.providers → api: "openai-completions" + baseUrl и apiKey
OpenAI SDK Передайте base_url и api_key в конструктор клиента (см. примеры кода ниже)
Любой HTTP-клиент Authorization: Bearer <ключ> + Content-Type: application/json
Важно: подключение работает только в инструментах, где можно явно задать свой Base URL. Если клиент жёстко зашит на api.openai.com — изменить это не получится.

Авторизация

Все запросы должны содержать заголовок:

bash
Authorization: Bearer sk-proxy-xxxxxxxxxxxxxxxx

Ключи создаются через регистрацию и раздел API Ключи. При отсутствии заголовка или неверном ключе API вернёт 401 Unauthorized.

POST /v1/chat/completions

Основной endpoint. Совместим с OpenAI Chat Completions API.

Если исходная модель временно недоступна, ProxAI может автоматически использовать fallback-маршрут, чтобы сохранить стабильность и не вернуть ошибку вашему серверу. Фактически использованная модель всегда приходит в usage.real_model, а точный порядок резервных моделей указан на странице моделей.

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

Параметр Тип Описание
model string required Alias модели. Например: gpt-4o, gpt-4.1-mini. Список — на странице моделей.
messages array required Массив сообщений. Каждый объект: {"role": "user"|"assistant"|"system", "content": "..."}.
stream boolean optional Включить SSE-стриминг. По умолчанию false.
temperature number optional Температура генерации от 0 до 2. По умолчанию зависит от модели.
max_tokens integer optional Максимальное число токенов в ответе.
top_p number optional Nucleus sampling. Альтернатива temperature.
stop string|string[] optional Стоп-последовательности.
n integer optional Число вариантов ответа. По умолчанию 1.
tools array optional Описание функций для function calling. См. раздел Функции (tools).
tool_choice string|object optional auto | none | required либо {"type":"function","function":{"name":"..."}} для принудительного вызова.

Параметры ответа

Поле Тип Описание
id string Уникальный ID запроса.
object string chat.completion
model string Alias модели, который был передан в запросе.
choices[].message.role string assistant
choices[].message.content string Текст ответа модели.
choices[].finish_reason string stop | length | tool_calls
usage.prompt_tokens integer Токены в запросе.
usage.completion_tokens integer Токены в ответе.
usage.total_tokens integer Сумма токенов.
usage.cost_credits float ProxAIСтоимость запроса в кредитах.
usage.real_model string ProxAIРеально использованная модель: может отличаться из-за экономного режима или fallback при недоступности primary.

ProxAI — поля, добавленные сверх стандарта OpenAI.

Пример ответа

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

Примеры кода

curl https://proxai.ru/v1/chat/completions \
  -H "Authorization: Bearer sk-proxy-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Привет!"}]
  }'
<?php
// Библиотека: openai-php/client — https://github.com/openai-php/client
// Установка:  composer require openai-php/client

$client = OpenAI::factory()
    ->withApiKey('sk-proxy-xxxxxxxx')
    ->withBaseUri('https://proxai.ru/v1')
    ->make();

$response = $client->chat()->create([
    'model'    => 'gpt-4o',
    'messages' => [['role' => 'user', 'content' => 'Привет!']],
]);

echo $response->choices[0]->message->content;
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]any{
        "model":    "gpt-4o",
        "messages": []map[string]string{{"role": "user", "content": "Привет!"}},
    })
    req, _ := http.NewRequest("POST", "https://proxai.ru/v1/chat/completions", bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer sk-proxy-xxxxxxxx")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    data, _ := io.ReadAll(resp.Body)
    fmt.Println(string(data))
}
// Библиотека: openai — https://www.npmjs.com/package/openai
// Установка:  npm install openai
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey:  'sk-proxy-xxxxxxxx',
  baseURL: 'https://proxai.ru/v1',
});

const res = await client.chat.completions.create({
  model:    'gpt-4o',
  messages: [{ role: 'user', content: 'Привет!' }],
});
console.log(res.choices[0].message.content);
POST /v1/chat/completions tools

Function calling — модель сама решает, когда вызвать вашу функцию, и возвращает её имя с аргументами. Совместимо с OpenAI: те же поля tools, tool_choice и ответ tool_calls.

Как это работает

  1. 1Вы передаёте в запросе массив tools с описанием функций (имя, описание, JSON Schema параметров).
  2. 2Если модель решает вызвать функцию — ответ приходит с finish_reason: "tool_calls" и массивом tool_calls (имя + аргументы в виде JSON-строки).
  3. 3Вы выполняете функцию у себя и отправляете результат вторым запросом — сообщением с role: "tool". Модель формирует финальный ответ.
Зависит от модели: function calling поддерживают не все модели. Если модель не умеет вызывать функции — она ответит обычным текстом. Для надёжного function calling используйте флагманские модели (GPT-4o, GPT-4.1, Claude, Gemini Pro).

Шаг 1. Запрос с описанием функции

curl https://proxai.ru/v1/chat/completions \
  -H "Authorization: Bearer sk-proxy-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      { "role": "user", "content": "Какая погода в Москве?" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Текущая погода в городе",
          "parameters": {
            "type": "object",
            "properties": {
              "city": { "type": "string" }
            },
            "required": ["city"]
          }
        }
      }
    ]
  }'
<?php
// Библиотека: openai-php/client

$response = $client->chat()->create([
    'model'    => 'gpt-4o',
    'messages' => [['role' => 'user', 'content' => 'Какая погода в Москве?']],
    'tools'    => [[
        'type' => 'function',
        'function' => [
            'name'        => 'get_weather',
            'description' => 'Текущая погода в городе',
            'parameters'  => [
                'type'       => 'object',
                'properties' => ['city' => ['type' => 'string']],
                'required'   => ['city'],
            ],
        ],
    ]],
]);

$call = $response->choices[0]->message->toolCalls[0] ?? null;
// $call->function->name → get_weather
// json_decode($call->function->arguments, true) → ['city' => 'Москва']
const res = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Какая погода в Москве?' }],
  tools: [{
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Текущая погода в городе',
      parameters: {
        type: 'object',
        properties: { city: { type: 'string' } },
        required: ['city'],
      },
    },
  }],
});

const call = res.choices[0].message.tool_calls?.[0];
// call.function.name → get_weather
// JSON.parse(call.function.arguments) → { city: 'Москва' }

Ответ с вызовом функции

json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\":\"Москва\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }],
  "usage": {
    "prompt_tokens": 52,
    "completion_tokens": 17,
    "total_tokens": 69,
    "cost_credits": 0.000091,
    "real_model": "openai/gpt-4o"
  }
}

Поле arguments — это строка с JSON, её нужно распарсить (JSON.parse / json_decode).

Шаг 2. Отправьте результат функции

Добавьте в историю ответ ассистента с tool_calls и результат выполнения функции (role: "tool"), затем повторите запрос:

json
{
  "model": "gpt-4o",
  "messages": [
    { "role": "user", "content": "Какая погода в Москве?" },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": { "name": "get_weather", "arguments": "{\"city\":\"Москва\"}" }
      }]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temp\": 18, \"sky\": \"облачно\"}"
    }
  ]
}
POST /v1/chat/completions stream: true

Потоковый ответ через Server-Sent Events (SSE). Добавьте stream: true в тело запроса.

Ответ приходит как поток событий text/event-stream. Каждое событие — строка вида data: {...}. Поток завершается строкой data: [DONE].

Перед [DONE] ProxAI отправляет финальный чанк с объектом usage, содержащим cost_credits и real_model.

Примеры кода

curl https://proxai.ru/v1/chat/completions \
  -H "Authorization: Bearer sk-proxy-xxxxxxxx" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Расскажи историю"}],
    "stream": true
  }'
<?php
// Библиотека: openai-php/client — https://github.com/openai-php/client
// Установка:  composer require openai-php/client

$client = OpenAI::factory()
    ->withApiKey('sk-proxy-xxxxxxxx')
    ->withBaseUri('https://proxai.ru/v1')
    ->make();

$stream = $client->chat()->createStreamed([
    'model'    => 'gpt-4o',
    'messages' => [['role' => 'user', 'content' => 'Расскажи историю']],
]);

foreach ($stream as $response) {
    echo $response->choices[0]->delta->content;
}
const stream = await client.chat.completions.create({
  model:    'gpt-4o',
  messages: [{ role: 'user', content: 'Расскажи историю' }],
  stream:   true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}
POST /v1/embeddings

Создаёт векторное представление текста. Используйте для семантического поиска, RAG и кластеризации.

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

Параметр Тип Описание
input string|string[] required Текст или массив текстов для векторизации.
model string optional По умолчанию text-embedding-3-small.
encoding_format string optional float (по умолчанию) или base64.

Доступные модели

Модель Вектор Описание
bge-m3 1024 Мультиязычная модель BAAI. Самая дешёвая, хороша на русском.
qwen3-embedding-8b 4096 Открытая модель Qwen. Выгодна на больших объёмах.
qwen3-embedding-4b 2560 Младшая версия Qwen3 Embedding.
text-embedding-3-small 1536 Базовая модель OpenAI, используется по умолчанию.
text-embedding-3-large 3072 Старшая модель OpenAI: выше качество поиска.
text-embedding-ada-002 1536 Legacy OpenAI — для совместимости со старым кодом.
gemini-embedding-001 3072 Модель Google, сильна на многоязычных корпусах.

Примеры кода

curl https://proxai.ru/v1/embeddings \
  -H "Authorization: Bearer sk-proxy-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "Текст для векторизации"
  }'
<?php

$response = $client->embeddings()->create([
    'model' => 'text-embedding-3-small',
    'input' => 'Текст для векторизации',
]);

$vector = $response->embeddings[0]->embedding; // float[]
const res = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'Текст для векторизации',
});
const vector = res.data[0].embedding; // number[]
POST /v1/images/generations

Генерация изображений по текстовому описанию. Совместим с OpenAI Images API — картинка возвращается в base64.

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

Параметр Тип Описание
prompt string required Описание желаемой картинки.
model string optional По умолчанию gemini-3.1-flash-image. Доступны также gemini-3-pro-image, gpt-5-image-mini, gpt-5.4-image.
n integer optional Сколько картинок сгенерировать, от 1 до 4 (по умолчанию 1). Каждая тарифицируется отдельно.
response_format string optional Только b64_json (по умолчанию). Ссылок на картинки мы не выдаём — файлы у себя не храним.

Формат картинки выбирает модель, а не запрос: Gemini отдаёт JPEG, поэтому сохранять байты в .png вслепую нельзя. Реальный формат приходит в поле output_format ответа (png, jpeg или webp).

Картинка тарифицируется не по токенам текста, а отдельной ставкой — цена за штуку указана на странице моделей. Списанные кредиты возвращаются в поле usage.cost_credits.

Примеры кода

curl https://proxai.ru/v1/images/generations \
  -H "Authorization: Bearer sk-proxy-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "рыжий кот в скафандре, студийный свет"
  }'
<?php
// Библиотека: openai-php/client

$response = $client->images()->create([
    'model'  => 'gemini-3.1-flash-image',
    'prompt' => 'рыжий кот в скафандре, студийный свет',
]);

// Расширение берём из ответа: модель может вернуть jpeg, а не png
$ext = $response->outputFormat ?? 'png';
file_put_contents("cat.{$ext}", base64_decode($response->data[0]->b64_json));
import fs from 'node:fs';

const res = await client.images.generate({
  model:  'gemini-3.1-flash-image',
  prompt: 'рыжий кот в скафандре, студийный свет',
});

// Расширение берём из ответа: модель может вернуть jpeg, а не png
const ext = res.output_format ?? 'png';
fs.writeFileSync(`cat.${ext}`, Buffer.from(res.data[0].b64_json, 'base64'));

Редактирование — POST /v1/images/edits

Исходная картинка (png/jpeg/webp до 8 МБ, до 4 штук) + промпт с описанием изменений — формат тот же multipart, что и у OpenAI, поэтому client.images.edit(...) из SDK работает как есть. Параметр mask не поддерживается — область изменения опишите словами в промпте.

bash
curl https://proxai.ru/v1/images/edits \
  -H "Authorization: Bearer sk-proxy-xxxxxxxx" \
  -F model="gemini-3.1-flash-image" \
  -F prompt="сделай чайник красным" \
  -F image="@teapot.jpg"
POST /v1/responses

Responses API — новый основной интерфейс OpenAI, в который по умолчанию ходят свежие SDK и агентские фреймворки. Поддерживает стриминг и вызов функций.

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

Параметр Тип Описание
input string|array required Строка или массив элементов диалога (сообщения, вызовы функций и их результаты).
model string required Алиас модели, как и в остальных endpoint-ах.
instructions string optional Системная инструкция — эквивалент сообщения с ролью system.
max_output_tokens integer optional Ограничение на длину ответа.
tools array optional Функции в плоском формате Responses: {"type":"function","name":…}.
text object optional Формат ответа, включая json_schema.
stream boolean optional Стриминг событиями response.* (SSE).

Чего пока нет

Ответы не сохраняются на нашей стороне, поэтому previous_response_id и conversation не поддерживаются — передавайте всю историю диалога в input. Параметр store принимается, но ничего не сохраняет. Встроенные инструменты OpenAI (web_search, file_search и подобные) исполняются на их серверах и у нас недоступны — на них приходит понятная ошибка 400, а не молчаливое игнорирование.

Примеры кода

curl https://proxai.ru/v1/responses \
  -H "Authorization: Bearer sk-proxy-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "instructions": "Отвечай кратко",
    "input": "Привет!"
  }'
# Библиотека: openai — pip install openai
from openai import OpenAI

client = OpenAI(
    api_key='sk-proxy-xxxxxxxx',
    base_url='https://proxai.ru/v1',
)

response = client.responses.create(
    model='gpt-4o',
    instructions='Отвечай кратко',
    input='Привет!',
)

print(response.output_text)
const response = await client.responses.create({
  model:        'gpt-4o',
  instructions: 'Отвечай кратко',
  input:        'Привет!',
});

console.log(response.output_text);
GET /v1/models

Список доступных алиасов в OpenAI-совместимом формате. Удобнее смотреть на странице моделей.

bash
curl https://proxai.ru/v1/models \
  -H "Authorization: Bearer sk-proxy-xxxxxxxx"

Отдельную модель можно запросить по её алиасу — некоторые SDK делают это при проверке настроек:

bash
curl https://proxai.ru/v1/models/gpt-4o \
  -H "Authorization: Bearer sk-proxy-xxxxxxxx"
POST /v1/completions

Старый текстовый endpoint OpenAI. Нужен только для интеграций, написанных до Chat Completions — в новом коде используйте /v1/chat/completions.

bash
curl https://proxai.ru/v1/completions \
  -H "Authorization: Bearer sk-proxy-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "prompt": "Столица Франции —"
  }'

Все модели каталога — чат-модели, поэтому промпт превращается в одно сообщение пользователя, а ответ приходит в поле choices[].text. Параметры echo, best_of, suffix и logprobs у чат-моделей смысла не имеют — на них приходит ошибка 400.

Коды ошибок

Тело ошибки всегда имеет вид: {"error": {"message": "...", "type": "...", "code": "..."}}

HTTP type / code Описание
401 invalid_api_key Неверный или отсутствующий API-ключ.
400 invalid_request_error Некорректный JSON, отсутствует model или messages.
402 insufficient_quota Недостаточно кредитов. Пополните баланс.
404 model_not_found Указанный alias модели не существует.
500 server_error Внутренняя ошибка ProxAI.
502 upstream_error Ошибка на стороне провайдера модели.