Chat Completions API

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

Защита от повторов. Для синхронных JSON-запросов к /v1/chat/completions и /v1/responses, а также для JSON-создания через /v1/images/* и /v1/videos* можно передать заголовок Idempotency-Key. Повтор того же запроса с тем же ключом вернёт сохранённый результат без второго обращения к модели и без двойного списания. Один ключ нельзя использовать для другого тела или endpoint. Для SSE, embeddings, moderation, audio и бинарных ответов этот заголовок не поддерживается. Ключ применяется только к созданию изображения или видео, а не к последующему чтению статуса или скачиванию файла.

Проверка параметров до списания

Сервер проверяет модель, модальность, обязательные поля и ограничения конкретного endpoint до резервирования баланса и обращения к модели. Некорректный запрос возвращает 400 invalid_request_error с полями code и param; деньги не блокируются.

• Для image-моделей проверяются size, aspect_ratio, quality, референсы и n. Для моделей с оплатой за запрос n должен быть равен 1.
• Для видео проверяются режим, длительность, размер/разрешение и число референсов. Специализированные Wan и Seedance запускаются через MegaAPI Chat.
• Для embeddings проверяются строковый input, батч до 2048 строк, размер текста и dimensions только для text-embedding-3-*.
• Для озвучки проверяются модель, голос, формат, скорость и лимит 8000 символов; для транскрипции нужен один файл.

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
    }
}

Ответ строго в JSON

Есть два способа попросить JSON, и они по-разному поддерживаются моделями:

• {"type": "json_object"} — «отвечай валидным JSON». Работает почти везде.
• {"type": "json_schema", "json_schema": {...}} — строгая схема: модель обязана вернуть ровно описанные поля. Поддерживают не все модели.

Строгая схема поддерживается не везде. Часть моделей отвечает на неё ошибкой 400 с текстом «response_format of type json_schema is not supported with this model» — так ведут себя, например, старые модели вроде gpt-3.5-turbo. Деньги за такой отказ не списываются, но запрос не выполняется.

Чтобы получать JSON стабильно на любой модели:

1. начните с {"type": "json_object"} — совместимость выше;
2. напишите в промпте прямо: «верни только JSON», и оставьте в тексте слово json — модели семейства Qwen без него отвечают ошибкой;
3. перед разбором ответа снимайте обёртки: ограждение ```json и блок <think>…</think>, который добавляют размышляющие модели;
4. если нужна именно строгая схема — проверьте её на своей модели одним запросом, прежде чем ставить в поток.

Стриминг (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-20251001, gemini-3.5-flash, gemini-3.1-pro-preview, gemini-2.5-pro, grok-4.3, qwen-vl-max, qwen3-vl-plus, seed-2-0-lite-260228.

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-1.5 и gpt-image-1 тарифицируются не за изображение, а по токенам: $9 и $57.6 за 1M у первой, $9 и $72 у второй. Неудачные генерации не списываются.

GPT-Image-2: три варианта

У gpt-image-2 три варианта с разной механикой управления размером, скоростью и ценой. Выбор между ними — это выбор между свободой размеров, скоростью и стоимостью.

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

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

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

Генерация по одному или нескольким фото-референсам (объект, стиль, персонаж, фон, «надень одежду»). Проще всего — в MegaAPI Chat: на вкладках «Генерация» и «Сравнение» прикрепите 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 доступны veo-3.1-generate-preview и veo-3.1-fast-generate-preview (текст→видео и картинка→видео). Модели doubao-seedance-2-0-* (со звуком), wan2.7-* (и wan2.6-*) (включая референс→видео и редактирование видео) доступны через MegaAPI Chat. Тарификация — по факту готовности: Seedance/Sora/Wan — по объёму (длительность и разрешение), Veo — за клип (Цены). Неудачные генерации не списываются. Полное описание режимов и контрактов — на странице Генерация видео.

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

1) POST https://megaapi.ru/v1/videos
{
    "model": "veo-3.1-generate-preview",
    "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 — теми же шагами, что и выше. Проще всего генерировать видео в MegaAPI Chat (вкладка «Видео»): все режимы и форматы уже настроены.

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

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

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

file=@audio.mp3
model=gpt-4o-transcribe
language=ru

response_format принимает json или text; verbose_json и таймкоды эти модели не поддерживают. Подробности — Распознавание речи.

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

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. Ответ ~100–500 мс, поддерживает русский и английский; списание выполняется по фактическому usage.

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-reranker-v2-m3 — мультиязычный, 1024 dim
• text-embedding-3-large — 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-flash-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-flash-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. Серверное состояние диалога не сохраняется: передавайте историю в input самостоятельно. Точный текущий список: gpt-5-pro, gpt-5.4-pro и gpt-5.5-pro. В каталоге они помечены protocol=responses; остальные модели не следует отправлять на этот endpoint.

from openai import OpenAI

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

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

Ключевые поля: model, input (обязательные), instructions, tools, reasoning, temperature, max_output_tokens, tool_choice, parallel_tool_calls. Поля previous_response_id, conversation, store=true и background=true возвращают понятную ошибку, поскольку шлюз не может безопасно восстановить их состояние и биллинг.

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

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

Списание происходит после каждого успешного запроса: в ответе всегда есть блок 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).

При временном rate limit или перегрузке ответ содержит Retry-After — число секунд до разумной повторной попытки (не больше 300). Шлюз не повторяет платный запрос автоматически. Для model_unavailable заголовок не возвращается: выберите другую совместимую модель вместо повтора.

{
    "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

При превышении лимита MegaAPI возвращает HTTP 429, код rate_limit_exceeded и заголовок Retry-After: 1. Лимиты применяются отдельно к адресу до проверки ключа и к пользователю после авторизации. При временной недоступности Redis остаётся локальный безопасный лимит процесса.