API Reference

MegaAPI.ru предоставляет полностью OpenAI-совместимый REST API. Base URL: https://megaapi.ru/v1

POST /v1/chat/completions

Главный эндпоинт — создаёт ответ модели на основе списка сообщений. Поддерживает обычный режим и потоковую выдачу (SSE).

Запрос

Явная резервная модель

Для /v1/chat/completions и /v1/responses можно заранее указать одну резервную модель заголовком X-MegaAPI-Fallback-Model. Это не автоматическая скрытая подмена: резерв используется только когда circuit основной модели уже открыт до сетевой отправки запроса.

Разрешённые варианты для конкретной модели доступны в справочном endpoint: GET /api/models/{model_id}/fallbacks. Сервер допускает только активную текстовую модель той же компании, с тем же API-протоколом, биллингом, типами входа и capabilities. Максимальная цена резерва не может превышать цену основной модели.

curl https://megaapi.ru/v1/chat/completions \
  -H "Authorization: Bearer sk-nexus-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "X-MegaAPI-Fallback-Model: gpt-5.6-terra" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [{"role": "user", "content": "Привет!"}]
  }'

Если резерв действительно выбран, ответ содержит заголовки X-MegaAPI-Model-Used и X-MegaAPI-Fallback-From. В обычном JSON-ответе поле model также содержит фактически использованный публичный ID. Для SSE ориентируйтесь на response headers.

Пример — Python (без стриминга)

from openai import OpenAI

client = OpenAI(
    base_url="https://megaapi.ru/v1",
    api_key="sk-nexus-xxxxxxxxxxxxxxxx",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "Ты полезный ассистент."},
        {"role": "user", "content": "Привет! Расскажи о себе."},
    ],
    max_tokens=512,
)

print(response.choices[0].message.content)

Пример — curl

curl https://megaapi.ru/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-nexus-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "Ты полезный ассистент."},
      {"role": "user", "content": "Привет!"}
    ]
  }'

Ответ

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1720000000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Я языковая модель GPT-4o..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 54,
    "total_tokens": 82
  }
}

Потоковая выдача (SSE)

При "stream": true ответ приходит в виде Server-Sent Events. Каждый chunk содержит дельту — фрагмент текста по мере генерации.

from openai import OpenAI

client = OpenAI(
    base_url="https://megaapi.ru/v1",
    api_key="sk-nexus-xxxxxxxxxxxxxxxx",
)

with client.chat.completions.stream(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Напиши хайку"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Формат SSE-сообщений:

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Привет"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"!"},"index":0}]}

data: {"id":"chatcmpl-abc","usage":{"prompt_tokens":10,"completion_tokens":5,"total_tokens":15},"choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

Function Calling / Tool Use

Передайте список инструментов и модель сама выберет, когда их вызвать.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Возвращает погоду в указанном городе",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "Название города"}
                },
                "required": ["city"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Какая погода в Москве?"}],
    tools=tools,
    tool_choice="auto",
)

Vision — изображения на вход

Передайте image_url в контенте сообщения. Поддерживают GPT-4o, Claude, Gemini, Grok.

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Что изображено на этом фото?"},
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/photo.jpg"},
                },
            ],
        }
    ],
)

Также поддерживаются base64-изображения через "url": "data:image/jpeg;base64,...".

JSON Mode и Structured Output

Два способа получить строго структурированный JSON.

JSON Object mode — модель всегда возвращает валидный JSON:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Верни список из 3 столиц в JSON"}],
    response_format={"type": "json_object"},
)

Structured Output — ответ строго соответствует вашей JSON Schema:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Извлеки данные о человеке"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age":  {"type": "integer"}
                },
                "required": ["name", "age"],
                "additionalProperties": False
            }
        }
    },
)

GET /v1/models

Возвращает список доступных моделей в формате OpenAI.

curl https://megaapi.ru/v1/models \
  -H "Authorization: Bearer sk-nexus-xxxxxxxxxxxxxxxx"

{
  "object": "list",
  "data": [
    {"id": "gpt-4o",              "object": "model", "owned_by": "openai"},
    {"id": "claude-sonnet-4-6",   "object": "model", "owned_by": "anthropic"},
    {"id": "gemini-2.5-pro",      "object": "model", "owned_by": "google"},
    ...
  ]
}

POST /v1/embeddings

Создаёт векторное представление текста.

response = client.embeddings.create(
    model="text-embedding-3-large",
    input="Hello, world!",
)
print(response.data[0].embedding[:5])  # [0.021, -0.003, ...]

POST /v1/audio/transcriptions

Распознавание речи сейчас недоступно — у поставщика нет ни одного канала расшифровки (проверено живым запросом 21 августа 2026). Подробности и что делать — на странице Распознавание речи.

Транскрипция аудио: gpt-4o-transcribe и gpt-4o-mini-transcribe. Модели Whisper мы не обслуживаем — запрос к whisper-1 вернёт ошибку. Параметры и цены — Распознавание речи.

with open("audio.mp3", "rb") as f:
    transcript = client.audio.transcriptions.create(
        model="gpt-4o-transcribe",
        file=f,
        language="ru",
    )
print(transcript.text)

POST /v1/images/generations

Генерация изображений по текстовому описанию (text-to-image). Эндпоинт совместим с OpenAI SDK.

response = client.images.generate(
    model="nano-banana-pro",
    prompt="Котёнок в стиле японской акварели",
    size="1024x1024",
    quality="high",   # для моделей, поддерживающих quality
    n=1,
)
print(response.data[0].url)

POST /v1/images/edits — редактирование по референсу (image-to-image)

Передайте одно или несколько изображений-референсов и опишите, что с ними сделать (в промпте можно ссылаться на «image 1», «image 2»). Поддерживают gpt-image-2/-vip/-all, nano-banana/-2/-pro, flux-kontext-*/flux-2-*, seedream-4-5-251128/seedream-5-0-260128.

# multipart/form-data — gpt-image-* и nano-banana-*
curl https://megaapi.ru/v1/images/edits \
  -H "Authorization: Bearer sk-nexus-xxxx" \
  -F model=gpt-image-2-all \
  -F 'prompt=Сделай из этого фото карточку товара на белом фоне' \
  -F image=@photo.png

Подробные контракты по каждому семейству (размеры, qualiy, watermark, мультиреференс) — в полном руководстве по изображениям.

Коды ошибок

Все ошибки возвращаются в формате OpenAI:

{
  "error": {
    "message": "Insufficient balance. Top up via Telegram bot.",
    "type": "insufficient_balance",
    "code": "balance_too_low"
  }
}

Быстрый старт с OpenAI SDK

Любая версия OpenAI SDK работает без изменений кода — только base_url и api_key:

# Python
pip install openai

from openai import OpenAI

client = OpenAI(
    base_url="https://megaapi.ru/v1",
    api_key="sk-nexus-xxxxxxxxxxxxxxxx",
)

// JavaScript / TypeScript
npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://megaapi.ru/v1",
  apiKey: "sk-nexus-xxxxxxxxxxxxxxxx",
});

Больше примеров — в разделе интеграций.