API Reference

MegaAPI.ru полностью реализует протокол OpenAI Chat Completions: те же эндпоинты, поля, заголовки и формат ошибок. Дополнительно поддержаны нативные форматы Anthropic Messages и Google generateContent — если вашему клиенту нужен именно «родной» формат провайдера.

POST /v1/chat/completions

Основной эндпоинт. Принимает массив сообщений, возвращает ответ модели. Полностью совместим с OpenAI SDK на любом языке.

Минимальный пример

POST https://megaapi.ru/v1/chat/completions
Authorization: Bearer sk-nexus-...
Content-Type: application/json

{
    "model": "gpt-5",
    "messages": [
        {"role": "system", "content": "Ты — поэт."},
        {"role": "user",   "content": "Напиши хайку про море."}
    ],
    "temperature": 0.8,
    "max_tokens": 512
}

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

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

{
    "id": "chatcmpl-abc123",
    "object": "chat.completion",
    "created": 1716900000,
    "model": "gpt-5",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Привет!"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 28,
        "completion_tokens": 5,
        "total_tokens": 33
    }
}

Стриминг (Server-Sent Events)

При "stream": true сервер отвечает потоком text/event-stream: каждый чанк — это data: {...json...}\n\n, последний — data: [DONE]. Финальный чанк перед [DONE] содержит блок usage — мы автоматически включаем stream_options.include_usage, чтобы получить точные токены для биллинга.

data: {"choices":[{"delta":{"content":"Пр"}}]}
data: {"choices":[{"delta":{"content":"ивет"}}]}
data: {"choices":[{"delta":{"content":"!"}, "finish_reason":"stop"}]}
data: {"usage":{"prompt_tokens":10,"completion_tokens":3,"total_tokens":13}}
data: [DONE]

Важно. Если вы за nginx/cloudflare — убедитесь, что proxy_buffering отключён, иначе клиент увидит ответ только после [DONE]. Наша инсталляция уже так настроена.

Function Calling / Tool Use

Совместимо с OpenAI Tool Use. Поддерживается всеми флагманскими моделями: GPT-5, Claude 4.6, Gemini 3 Pro, Grok 4, DeepSeek V3.

{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Какая погода в Москве?"}],
    "tools": [{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Возвращает текущую погоду в городе",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"}
                },
                "required": ["city"]
            }
        }
    }],
    "tool_choice": "auto"
}

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

Передавайте картинки прямо в messages как объект с type: "image_url". URL-ы и base64 data-URI поддерживаются.

{
    "model": "gpt-5",
    "messages": [{
        "role": "user",
        "content": [
            {"type": "text", "text": "Что на фото?"},
            {"type": "image_url",
             "image_url": {"url": "https://example.com/cat.jpg"}}
        ]
    }]
}

Vision поддерживают: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5, gpt-4o, gpt-4.1, claude-opus-4.7, claude-sonnet-4.6, claude-haiku-4.5, gemini-3.5-flash, gemini-3.1-pro-preview, gemini-2.5-pro, grok-4.3, qwen-vl-max, pixtral-large, seed-2.0-lite, mimo-v2-omni.

POST /v1/images/generations

Генерация изображений. Совместимо с DALL·E / OpenAI Images API.

POST https://megaapi.ru/v1/images/generations
{
    "model": "nano-banana-pro",
    "prompt": "астронавт верхом на гепарде в киберпанк-городе, неон, 4k",
    "size": "1024x1024",
    "n": 1,
    "response_format": "url"
}

Доступные модели генерации

GPT-Image-2: три варианта одной модели

У gpt-image-2 три канала с разной механикой управления размером и ценой. Официальный канал даёт полную свободу размеров, reverse-каналы (-vip, -all) дешевле — $0.044/img.

30 поддерживаемых размеров у gpt-image-2-vip (10 соотношений × 3 тира):

Срок жизни image-URL. Возвращаемые ссылки на сгенерированные картинки живут ~24 часа (R2 CDN). Скачайте и положите в своё хранилище сразу после генерации. Альтернатива — "response_format": "b64_json": вы получите base64 прямо в ответе.

Редактирование и image-to-image (по референсу)

Генерация по одному или нескольким фото-референсам (объект, стиль, персонаж, фон, «надень одежду»). Проще всего — в ИИ-Студии: на вкладках «🖼 Генерация» и «⚖️ Сравнение» прикрепите 1–4 фото в поле «Референс», и модель отредактирует/совместит их по описанию (ссылайтесь на фото как «image 1», «image 2»). Поддерживают gpt-image-2-all/-vip/gpt-image-2, nano-banana/-2/-pro, flux-kontext-*/flux-2-*, seedream-4-5-251128/seedream-5-0-260128.

Через API формат зависит от семейства модели:

gpt-image-* и nano-banana-* — multipart-форма, поле image (повторяйте для нескольких фото):

POST https://megaapi.ru/v1/images/edits
Content-Type: multipart/form-data

model=gpt-image-2-all
prompt=Помести персонажа из image 1 в сцену из image 2
image=@person.png
image=@scene.png
mask=@mask.png        (опц., inpaint — для gpt-image-2)
response_format=url

flux-* — JSON в /images/generations, референс в input_image (URL или base64), доп. фото — input_image_2…8:

POST https://megaapi.ru/v1/images/generations
{
    "model": "flux-kontext-pro",
    "prompt": "Естественно совмести оба изображения",
    "input_image": "data:image/png;base64,…",
    "aspect_ratio": "16:9"
}

seedream-* — JSON в /images/generations, массив публичных URL в поле image:

POST https://megaapi.ru/v1/images/generations
{
    "model": "seedream-5-0-260128",
    "prompt": "Замени одежду в image 1 на наряд из image 2",
    "image": ["https://.../person.png", "https://.../outfit.png"],
    "sequential_image_generation": "disabled",
    "size": "2048x2048"
}

POST /v1/chat/completions — image gen через чат

Все gpt-image-2-* и nano-banana-* также вызываются через обычный chat-API. Просто укажите соответствующую модель и попросите сгенерировать изображение в обычном prompt — в ответ придёт URL картинки внутри message.content:

{
    "model": "gpt-image-2-all",
    "messages": [{
        "role": "user",
        "content": "Сгенерируй: 16:9 закат, силуэт горы, мягкий розовый свет."
    }]
}

Генерация видео (асинхронно)

Через прямой API /v1/videos доступны sora-2, sora-2-pro, veo-3.1-generate-preview, veo-3.1-fast-generate-preview (текст→видео и картинка→видео). Модели wan2.7-* и happyhorse-1.0-* (включая референс→видео и редактирование видео) доступны через ИИ-Студию. Тарификация — по факту готовности: Sora/Wan/HappyHorse — по длительности и разрешению, Veo — за клип (Цены). Неудачные генерации не списываются. Полное описание режимов и контрактов — на странице Генерация видео.

Проще всего — через ИИ-Студию (вкладка «🎬 Видео»): выбор/вставка модели, все режимы (t2v / i2v / r2v / video-edit), прогресс, плеер и история. Напрямую через API (sora/veo):

1) POST https://megaapi.ru/v1/videos
{
    "model": "sora-2",
    "prompt": "slow-motion wave crashing on a cliff at sunset",
    "seconds": "8",            // "4" | "8" | "12"
    "size": "1280x720"
}
→ { "id": "video_...", "status": "queued" }

2) GET https://megaapi.ru/v1/videos/{id}          // поллинг: queued → in_progress → completed
3) GET https://megaapi.ru/v1/videos/{id}/content  // готовый MP4 (бинарный, нужен Bearer)

Image-to-video. Передаётся как multipart/form-data с файлом input_reference (размеры картинки должны совпадать с size). Поллинг статуса и получение готового MP4 — теми же шагами, что и выше. Проще всего генерировать видео в ИИ-Студии (вкладка «🎬 Видео»): все режимы и форматы уже настроены.

Аудио: транскрипция и синтез

Транскрипция (speech → text):

POST https://megaapi.ru/v1/audio/transcriptions
Content-Type: multipart/form-data

file=@audio.mp3
model=whisper-large-v3
response_format=verbose_json
language=ru

Синтез речи (text → speech): модели tts-1, tts-1-hd, gemini-2.5-flash-tts, gemini-2.5-pro-tts. Удобно озвучивать прямо в ИИ-Студии (вкладка «🔊 Озвучка»): текст → голос → плеер и история.

POST https://megaapi.ru/v1/audio/speech
{
    "model": "tts-1-hd",
    "voice": "alloy",
    "input": "Привет, это синтезированная речь.",
    "response_format": "mp3"
}

Анализ видео (video understanding)

Отправьте видео в Gemini-модель через /v1/chat/completions — распознавание сцен, действий, текста на кадрах и ссылки по таймкодам. Видео передаётся как base64 (до 20 МБ) в виде элемента image_url внутри content, либо как ссылка на YouTube. Модели: gemini-3.5-flash (баланс цена/скорость) или gemini-3.1-pro-preview (глубокий анализ). Прямые ссылки на .mp4 не поддерживаются — только base64 или YouTube.

Модерация контента

POST /v1/moderations — проверка текста на нарушения (hate, harassment, sexual, violence и др.). Модели: omni-moderation-latest, text-moderation-stable. Ответ ~100–500 мс, поддерживает русский и английский.

POST https://megaapi.ru/v1/moderations
{ "model": "omni-moderation-latest", "input": "текст для проверки" }
→ { "results": [{ "flagged": false, "categories": {…}, "category_scores": {…} }] }

Embeddings

Векторизация текста для поиска и RAG.

POST https://megaapi.ru/v1/embeddings
{
    "model": "text-embedding-3-large",
    "input": ["Первый текст", "Второй текст"],
    "encoding_format": "float"
}

Поддерживаемые модели:

• text-embedding-3-large — OpenAI, 3072 dim
• text-embedding-3-small — OpenAI, 1536 dim, дешевле
• text-embedding-ada-002 — legacy
• bge-m3 — мультиязычный, 1024 dim
• cohere-embed-v3 — Cohere multilingual

Claude native (Messages API)

Если вы используете официальный anthropic SDK (Python / @anthropic-ai/sdk) и хотите оставить нативный формат — используйте эндпоинт /v1/messages. Заголовки те же, что у Anthropic: x-api-key (ваш sk-nexus-... ключ) и anthropic-version: 2023-06-01.

POST https://megaapi.ru/v1/messages
x-api-key: sk-nexus-...
anthropic-version: 2023-06-01
content-type: application/json

{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Привет"}]
}

Официальный Python-SDK — просто подмените base_url на наш шлюз:

# pip install anthropic
import anthropic

client = anthropic.Anthropic(
    api_key="sk-nexus-...",
    base_url="https://megaapi.ru",   # без /v1 — SDK сам добавит /v1/messages
)

msg = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Напиши quicksort на Python"}],
)
print(msg.content[0].text)

Claude-модели также доступны через обычный OpenAI-совместимый /v1/chat/completions — удобно, если проект уже на OpenAI SDK. Но кэш промпта (prompt caching) считается только в нативном формате /v1/messages, поэтому для высокочастотных сценариев с длинным общим префиксом выбирайте native-формат.

Кэширование промпта (Prompt Caching)

Пометьте длинный переиспользуемый префикс (системные инструкции, большой документ, few-shot примеры) полем cache_control — сервер сохранит его, и повторные запросы с тем же префиксом будут обрабатываться в ~10× быстрее и дешевле. Кэш-поля передаются сквозь наш шлюз без изменений, биллинг — по официальным множителям Anthropic.

{
    "model": "claude-sonnet-4-6",
    "max_tokens": 256,
    "messages": [{
        "role": "user",
        "content": [
            {"type": "text", "text": "<большой документ…>",
             "cache_control": {"type": "ephemeral"}},
            {"type": "text", "text": "Ваш вопрос по документу"}
        ]
    }]
}

Правила и тарификация (множители к базовой цене input-токенов):

• cache_control крепится только к объекту content-блока, не к строке. Стабильную часть ставьте первой, изменяемую — после маркера.
• Минимум токенов для кэширования: Sonnet 4.5 — 1024, Sonnet 4.6 — 2048, Opus 4.5/4.6/4.7 и Haiku 4.5 — 4096. Меньше — кэш молча пропускается.
• TTL — «скользящее окно»: каждое попадание сбрасывает таймер, активные диалоги не протухают.
• До 4 точек cache_control на запрос; кэш — префиксный (байты до маркера должны совпадать с прошлым запросом).
• Окупаемость — уже с 2-го переиспользования: 1.25 + 0.1 = 1.35 против 2.0 без кэша. Попадание — когда cache_read_input_tokens > 0.

Расширенное мышление и параметр effort

Управляйте глубиной рассуждений Claude. У Opus 4.7 / 4.8 используется адаптивное мышление (thinking.type: "adaptive") — модель сама выбирает глубину; формат type: "enabled" + budget_tokens у них вернёт 400. Альтернатива — суффикс модели -thinking (напр. claude-sonnet-4-6-thinking), который включает мышление без правки тела запроса.

{
    "model": "claude-opus-4-8",
    "max_tokens": 16000,
    "thinking": {"type": "adaptive", "display": "summarized"},
    "output_config": {"effort": "xhigh"},
    "messages": [{"role": "user", "content": "Сравни микросервисы и монолит"}]
}

Параметр effort лежит в верхнеуровневом output_config (не внутри thinking). Уровни: low · medium · high (по умолчанию) · xhigh · max. Рекомендация: для кодинга/агентных задач — xhigh, для прочих интеллектуально-ёмких — high; при высоких уровнях ставьте max_tokens до 64k. Beta-заголовок не нужен — effort открыт для всех поддерживаемых моделей. Блоки рассуждений приходят в ответе как элементы content с "type": "thinking", финальный ответ — "type": "text".

Gemini native (generateContent)

Нативный формат Google — эндпоинт /v1beta/models/{model}:generateContent (стриминг — :streamGenerateContent). Ключ передаётся как query-параметр ?key= или заголовок x-goog-api-key. Указывайте именно наш ключ sk-nexus-..., а не ключ Google AI Studio.

POST https://megaapi.ru/v1beta/models/gemini-3-pro-preview:generateContent?key=sk-nexus-...
{
    "contents": [{
        "role": "user",
        "parts": [{"text": "Привет"}]
    }]
}

Через официальный google-genai SDK подмените base_url:

# pip install google-genai
from google import genai

client = genai.Client(
    api_key="sk-nexus-...",
    http_options={"base_url": "https://megaapi.ru"},
)

resp = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Объясни квантовую запутанность простыми словами",
    config={"thinking_budget": 8192, "temperature": 1.0, "include_thoughts": True},
)
print(resp.text)

• Мультимодальность. Картинки/аудио/видео — элементами parts (inline_data base64 или PIL-Image в SDK). Лимит файла — до 20 МБ; Files API не поддерживается.
• Рассуждения. Глубину chain-of-thought задаёт thinking_budget (0–16384 токенов), include_thoughts: true вернёт краткое резюме мыслей.
• Функции (tools). function_declarations + tool_config.function_calling_config.mode = "AUTO".
• Учёт токенов. В ответе — usage_metadata с полями prompt_token_count, candidates_token_count, cached_content_token_count, thoughts_token_count.

POST /v1/responses (OpenAI Responses API)

Поддержан агентный интерфейс OpenAI Responses API. В отличие от /v1/chat/completions (где история — массив messages), здесь запрос упрощён до input + instructions, а состояние диалога сохраняется на стороне сервера через previous_response_id. Поддерживают только новые модели (o3, o3-pro, o4-mini, gpt-4.1, gpt-5.x); старые (gpt-3.5) — нет.

from openai import OpenAI

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

resp = client.responses.create(
    model="gpt-5.4",
    input="Чем помочь сегодня?",
    instructions="Ты — лаконичный ассистент.",
    reasoning={"effort": "medium"},   # low | medium | high — для reasoning-моделей
)
print(resp.output[0].content[0].text)

Ключевые поля: model, input (обязательные), instructions, tools (function calling / code interpreter / file search), reasoning, previous_response_id (связка диалога), store (по умолчанию true), temperature, max_output_tokens, tool_choice, parallel_tool_calls. Reasoning-токены o3/o4-mini сохраняются между запросами.

Проверка баланса и расхода

Текущий баланс, бонусы и историю списаний удобнее всего смотреть в Личном кабинете и Telegram-боте @megaapibot (он же присылает уведомление при низком балансе). Программно цены всех моделей (уже с нашей наценкой) отдаёт GET https://megaapi.ru/api/models — это та же таблица, что в каталоге и Студии.

Списание происходит после каждого успешного запроса: в ответе всегда есть блок usage (prompt_tokens / completion_tokens / total_tokens), по которому вы можете считать расход на своей стороне в реальном времени. Запросы, завершившиеся ошибкой (4xx/5xx), не тарифицируются.

GET /v1/models

Получить список доступных моделей и их характеристик.

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

Ошибки

Формат 1:1 совместим с OpenAI. Каждая ошибка возвращает HTTP-код и JSON c полями message, type, code (опционально param).

{
    "error": {
        "message": "Balance is empty. Top up via @megaapibot to continue.",
        "type": "invalid_request_error",
        "code": "insufficient_balance",
        "param": null
    }
}

Аутентификация и баланс

Запрос

Rate-limit и upstream

Retry-стратегия

Мы рекомендуем экспоненциальный бэкофф для кодов 429, 500, 502, 503, 504:

retries = 5
delays = [1, 2, 5, 15, 30]  # секунды
# Любая клиентская ошибка 4xx (кроме 429) — без ретрая

Failed requests не списываются. Если запрос вернул HTTP 4xx или 5xx — баланс не уменьшается. Списание происходит только после успешного ответа провайдера и получения usage.

Лимиты и rate-limit

В ответах присутствуют стандартные rate-limit заголовки:

x-ratelimit-limit-requests: 200
x-ratelimit-remaining-requests: 199
x-ratelimit-reset-requests: 0.5s
x-ratelimit-limit-tokens: 2000000
x-ratelimit-remaining-tokens: 1948872
x-ratelimit-reset-tokens: 1.234s