Документация
API Reference
ProxAI полностью совместим с OpenAI API — те же endpoint-ы, те же параметры.
Где взять ключ, куда вставить Base URL, как проверить что работает.
Перейти →Endpoint-ы, параметры запроса/ответа, авторизация, примеры на bash/PHP/Go/JS.
Перейти →Endpoint-ы
Все пути относительно Base URL. Ниже — параметры и примеры по каждому.
/v1/chat/completions
/v1/responses
/v1/images/generations
/v1/images/edits
/v1/embeddings
/v1/completions
/v1/models
Подключение клиента
Для работы нужны только два параметра: Base URL и API Key.
https://proxai.ru/v1
Зарегистрируйтесь, чтобы создать API-ключ — скопировать его можно в любой момент в разделе «API Ключи».
Как настроить в популярных инструментах
Авторизация
Все запросы должны содержать заголовок:
Authorization: Bearer sk-proxy-xxxxxxxxxxxxxxxx
Ключи создаются через регистрацию и раздел API Ключи.
При отсутствии заголовка или неверном ключе API вернёт 401 Unauthorized.
/v1/chat/completions
Основной endpoint. Совместим с OpenAI Chat Completions API.
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.
Пример ответа
{
"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);
/v1/chat/completions
tools
Function calling — модель сама решает, когда вызвать вашу функцию, и возвращает её имя с аргументами. Совместимо с OpenAI: те же поля tools, tool_choice и ответ tool_calls.
Как это работает
- 1Вы передаёте в запросе массив
toolsс описанием функций (имя, описание, JSON Schema параметров). - 2Если модель решает вызвать функцию — ответ приходит с
finish_reason: "tool_calls"и массивомtool_calls(имя + аргументы в виде JSON-строки). - 3Вы выполняете функцию у себя и отправляете результат вторым запросом — сообщением с
role: "tool". Модель формирует финальный ответ.
Шаг 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: 'Москва' }
Ответ с вызовом функции
{
"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"), затем повторите запрос:
{
"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\": \"облачно\"}"
}
]
}
/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 ?? '');
}
/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[]
/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 не поддерживается — область изменения опишите словами в промпте.
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"
/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);
/v1/models
Список доступных алиасов в OpenAI-совместимом формате. Удобнее смотреть на странице моделей.
curl https://proxai.ru/v1/models \
-H "Authorization: Bearer sk-proxy-xxxxxxxx"
Отдельную модель можно запросить по её алиасу — некоторые SDK делают это при проверке настроек:
curl https://proxai.ru/v1/models/gpt-4o \
-H "Authorization: Bearer sk-proxy-xxxxxxxx"
/v1/completions
Старый текстовый endpoint OpenAI. Нужен только для интеграций, написанных до Chat Completions — в новом коде используйте /v1/chat/completions.
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 |
Ошибка на стороне провайдера модели. |