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

Совместимо с OpenAI и Anthropic. Укажите в любом SDK адрес https://api.ultragpt.pro/v1.

  1. Создайте API-ключ и сохраните его как ULTRAGPT_API_KEY.
  2. Пополните баланс (общий с приложением UltraGPT).
  3. Установите SDK (pip install openai / npm i openai) и вызовите модель:
curl https://api.ultragpt.pro/v1/chat/completions \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'

Эндпоинты

POST/chat/completionsChat completion (формат OpenAI), со стримингом или без.
POST/messagesAnthropic Messages API (Anthropic SDK, Claude Code).
POST/messages/count_tokensОценка числа токенов (формат Anthropic).
POST/responsesOpenAI Responses API с хранением диалогов.
GET/responses/{id}Сохранённый ответ (также DELETE, /input_items).
POST/completionsУстаревший text completions.
POST/embeddingsЭмбеддинги текста.
POST/images/generationsГенерация изображений.
POST/images/editsРедактирование загруженных изображений (multipart, images.edit в OpenAI SDK).
POST/audio/speechСинтез речи.
POST/audio/transcriptionsРаспознавание речи (также /audio/translations).
POST/filesЗагрузка файла для Batch (также GET, DELETE, /content).
POST/batchesДо 5000 запросов асинхронно, вне лимитов запросов (также GET, /cancel).
POST/rerankРанжирование документов по запросу (Cohere / Voyage / Qwen).
POST/moderationsПроверка текста и изображений на вредный контент. Бесплатно.
POST/videosЗапуск генерации видео (асинхронно; также GET, GET /content, DELETE).
WS/realtime?model=Голос в реальном времени по WebSocket (протокол OpenAI Realtime).
POST/search/{engine}Отдельный веб-поиск (Tavily, Exa, Perplexity…), оплата за запрос.
GET/modelsМодели, доступные ключу (фильтры ?type=, ?supported_parameters=, ?input_modalities=; также /models/count).
GET/presetsПресеты рабочего пространства (изменение — ключом управления).
GET/keysКлючи управления: список, создание, изменение, отзыв ключей.
GET/activityРасход по дням, моделям и эндпоинтам за 30 дней.
POST/generations/lookupСтоимость и статистика до 1000 запросов сразу.
GET/keyТекущий ключ: лимиты, расходы.
GET/creditsБаланс и итоги.
GET/generation?id=Токены, стоимость и задержка запроса.

Аутентификация

Передавайте ключ как Authorization: Bearer <key> или x-api-key: <key> (Anthropic SDK). Ключи начинаются с ugpt_live_ или ugpt_test_; тестовые ключи имеют низкие лимиты, но списывают реальные кредиты.

Защищайте ключи на странице API-ключей: месячный лимит, список моделей, меньший RPM, срок действия, режим «только чтение» (без платных вызовов), список IP / CIDR и — для ключей в браузере — разрешённые домены по Origin / Referer. Перевыпуск меняет секрет, старый может работать ещё какое-то время. Отозванный ключ сразу перестаёт работать.

SDK и инструменты

Всё, что работает с OpenAI API, заработает с нашим адресом и ключом:

import { createOpenAI } from '@ai-sdk/openai'
import { generateText } from 'ai'

const ultragpt = createOpenAI({ baseURL: 'https://api.ultragpt.pro/v1', apiKey: process.env.ULTRAGPT_API_KEY })

const { text } = await generateText({ model: ultragpt.chat('grok-4.7'), prompt: 'Hello!' })

Пошаговые инструкции для Cursor, Cline, Claude Code, Codex CLI, Open WebUI, n8n и других: Интеграции.

Anthropic SDK и Claude Code

POST /v1/messages реализует Anthropic Messages API — системные промпты, изображения, документы, tool use, thinking, cache_control и события стриминга — для всех чат-моделей. Серверный инструмент web_search работает через наш веб-поиск.

curl https://api.ultragpt.pro/v1/messages \
  -H "x-api-key: $ULTRAGPT_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'

Claude Code — задайте переменные перед запуском claude:

Shell
export ANTHROPIC_BASE_URL="https://api.ultragpt.pro"
export ANTHROPIC_AUTH_TOKEN="$ULTRAGPT_API_KEY"
export ANTHROPIC_MODEL="claude-opus-4.6"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4.6"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-opus-4.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-5.5"
claude

Переход на UltraGPT

При переходе с OpenAI, OpenRouter или Anthropic меняются только адрес и ключ. Строки с + и - ниже — это весь переход.

from openai import OpenAI

client = OpenAI(
-    api_key=os.environ["OPENAI_API_KEY"],
+    base_url="https://api.ultragpt.pro/v1",
+    api_key=os.environ["ULTRAGPT_API_KEY"],
)
# Everything else stays: chat.completions, responses, embeddings,
# images, audio, files, batches. Pick any model from /v1/models:
response = client.chat.completions.create(model="grok-4.7", messages=messages)
  • Идентификаторы моделей: GET /v1/models или страница «Модели»; идентификаторы других провайдеров не подставляются.
  • Оплата предоплатная: сначала пополните баланс. Лимиты можно задать для ключа и на день.
  • Неподдерживаемые параметры отбрасываются и перечисляются в заголовке x-ultragpt-ignored-params, а не вызывают ошибку.
  • Сгенерированные клиенты: спецификация OpenAPI (/openapi.json) или коллекция Postman. Postman / Bruno / Insomnia

Рецепты

Рецепты под конкретные задачи, сочетающие несколько возможностей. Каждый работает как есть с официальным Python SDK OpenAI.

Надёжные запросы: резерв, повторы, без двойной оплаты

Python
# Never lose a request and never pay twice: fallbacks + retries +
# an Idempotency-Key that makes a retry replay the first answer.
import os, uuid
from openai import OpenAI

client = OpenAI(base_url="https://api.ultragpt.pro/v1", api_key=os.environ["ULTRAGPT_API_KEY"],
                max_retries=4)  # SDK backs off on 429/5xx, honors retry-after

def ask(messages):
    return client.chat.completions.create(
        model="grok-4.7",
        messages=messages,
        extra_body={"models": ["gpt-6-astra"]},  # routed here if the first fails
        extra_headers={"Idempotency-Key": str(uuid.uuid4())},
    )

Извлечение данных по JSON-схеме

Python
# Extract typed data: strict JSON schema in, validated object out.
schema = {
    "name": "invoice",
    "strict": True,
    "schema": {
        "type": "object",
        "properties": {
            "vendor": {"type": "string"},
            "total": {"type": "number"},
            "due_date": {"type": "string"},
        },
        "required": ["vendor", "total", "due_date"],
        "additionalProperties": False,
    },
}
r = client.chat.completions.create(
    model="grok-4.7",
    messages=[{"role": "user", "content": invoice_text}],
    response_format={"type": "json_schema", "json_schema": schema},
    extra_body={"plugins": [{"id": "response-healing"}]},  # repairs broken JSON
)
data = json.loads(r.choices[0].message.content)

Точная стоимость для ваших клиентов

Python
# Bill your own customers: tag each request, then read the exact cost.
r = client.chat.completions.with_raw_response.create(
    model="grok-4.7",
    messages=messages,
    extra_body={"safety_identifier": hashed_customer_id},
)
generation_id = r.headers["x-ultragpt-generation-id"]

# Later (or in bulk, up to 1000 ids):
import httpx
costs = httpx.post("https://api.ultragpt.pro/v1/generations/lookup",
    headers={"Authorization": f"Bearer {os.environ['ULTRAGPT_API_KEY']}"},
    json={"ids": [generation_id]}).json()
print(costs["summary"]["total_cost"])  # USD actually billed

Поиск: эмбеддинги + rerank

Python
# Retrieval: embed, shortlist by cosine similarity, rerank, answer.
import numpy as np

def embed(texts):
    r = client.embeddings.create(model="qwen3-embedding-8b", input=texts)
    return np.array([d.embedding for d in r.data])

doc_vectors = embed(documents)                       # once, then store
q = embed([question])[0]
scores = doc_vectors @ q / (np.linalg.norm(doc_vectors, axis=1) * np.linalg.norm(q))
shortlist = [documents[i] for i in scores.argsort()[::-1][:20]]

ranked = httpx.post("https://api.ultragpt.pro/v1/rerank",
    headers={"Authorization": f"Bearer {os.environ['ULTRAGPT_API_KEY']}"},
    json={"model": "cohere-rerank-v3.5", "query": question,
          "documents": shortlist, "top_n": 4}).json()["results"]
context = "\n\n".join(shortlist[r["index"]] for r in ranked)

Большие задачи через Batch API

Python
# Thousands of prompts overnight at the batch discount.
import json
with open("requests.jsonl", "w") as f:
    for i, text in enumerate(texts):
        f.write(json.dumps({"custom_id": f"row-{i}", "method": "POST",
            "url": "/v1/chat/completions",
            "body": {"model": "grok-4.7",
                     "messages": [{"role": "user", "content": text}]}}) + "\n")

file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
batch = client.batches.create(input_file_id=file.id,
    endpoint="/v1/chat/completions", completion_window="24h")
# Poll client.batches.retrieve(batch.id) (or use the batch webhook), then:
results = client.files.content(batch.output_file_id).text

Chat completions

POST /chat/completions принимает:

modelОбязательно. Id модели из /models или @preset/<slug>. Суффиксы: :online (веб-поиск), :nitro (быстрейший поставщик), :floor (дешевле всего), :exacto (лучший вызов инструментов), :thinking (рассуждения).
presetСлаг пресета; поля запроса важнее.
messagesОбязательно. Формат OpenAI: text, image_url и file; сообщения tool.
modelsДо 2 резервных моделей, по порядку при сбое основной.
stream, stream_options.include_usageServer-sent events; финальный чанк с расходом и стоимостью.
max_tokens / max_completion_tokensЛимит генерации; также определяет нужный для запроса баланс.
temperature, top_p, top_k, min_p, stop, seedПараметры сэмплинга (зависят от модели).
presence_penalty, frequency_penalty, repetition_penalty, logit_biasШтрафы токенов.
tools, tool_choice, parallel_tool_callsВызов функций.
response_formatjson_object или json_schema (структурированный вывод).
reasoning, reasoning_effort, include_reasoningМодели с рассуждениями.
pluginsweb (поиск), response-healing (починка JSON), context-compression (сжатие длинных промптов). У каждого есть "enabled": false.
transforms["middle-out"] — то же, что context-compression; [] отключает.
safety_identifier, prompt_cache_keyId конечного пользователя (видно в активности) и подсказка кэша OpenAI.
providerНастройки маршрутизации (см. ниже).
logprobs, top_logprobs, modalities, prediction, userПередаются, где поддерживаются.

Неизвестные параметры игнорируются и перечисляются в заголовке x-ultragpt-ignored-params ; n должно быть 1. У каждого ответа свой id (также в x-ultragpt-generation-id), модель, которая ответила, и usage.cost — списанная сумма в USD.

Responses API

POST /responses поддерживает input items, instructions, function tools, инструмент web_search, text.format (JSON schema) и reasoning. При store (по умолчанию true) диалог хранится 30 дней в зашифрованном виде, поэтому работает previous_response_id ; передайте store: false, чтобы отказаться.

curl https://api.ultragpt.pro/v1/responses \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "grok-4.7", "input": "What is an API?" }'

Стриминг

При stream: true приходят события chat.completion.chunk, в конце — data: [DONE]. Добавьте stream_options: {"include_usage": true}, чтобы получить финальный чанк с расходом и стоимостью. Если отключиться посреди стрима, генерация всё равно завершится и будет оплачена полностью, по точному расходу. Отправьте X-UltraGPT-Abort-On-Disconnect: true, чтобы вместо этого остановить её: оплачивается только выданный до отключения ответ (оценочно — поставщик не сообщает расход прерванного стрима).

curl https://api.ultragpt.pro/v1/chat/completions \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -N -d '{
    "model": "grok-4.7",
    "stream": true,
    "messages": [{ "role": "user", "content": "Write a haiku about APIs" }]
  }'

Инструменты и JSON

Вызов функций и структурированный вывод — в формате OpenAI. Запрос с tools к модели без их поддержки сразу получает 400 unsupported_parameter.

response = client.chat.completions.create(
    model="grok-4.7",
    messages=[{"role": "user", "content": "Extract: Ada Lovelace, born 1815"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"name": {"type": "string"}, "born": {"type": "integer"}},
                "required": ["name", "born"],
                "additionalProperties": False,
            },
        },
    },
)

Рассуждения

Используйте reasoning_effort или объект reasoning ({ effort, max_tokens, exclude }). Текст рассуждений возвращается в message.reasoning (delta.reasoning при стриминге); токены рассуждений оплачиваются как выходные.

response = client.chat.completions.create(
    model="grok-4.7",
    messages=[{"role": "user", "content": "How many r's are in strawberry?"}],
    reasoning_effort="high",  # or extra_body={"reasoning": {"max_tokens": 4000, "exclude": False}}
)
print(response.choices[0].message.reasoning)  # the model's reasoning, when returned
print(response.usage.completion_tokens_details.reasoning_tokens)

Изображения и файлы

Отправляйте части image_url с https-ссылкой или base64 data URL (до 20 изображений по 20 МБ) моделям с поддержкой зрения, а PDF — как части file. Другие модели отклоняют изображения с кодом 400. Тело запроса — не более 10 МБ; большие изображения передавайте ссылкой.

Веб-поиск

Добавьте plugins: [{ "id": "web" }] или допишите :online к id модели. Мы ищем в интернете по последнему сообщению пользователя, передаём результаты модели и возвращаем их как аннотации url_citation. Каждый поиск оплачивается по цене со страницы моделей.

curl https://api.ultragpt.pro/v1/chat/completions \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7:online",
    "messages": [{ "role": "user", "content": "What happened in AI this week?" }]
  }'

Маршрутизация по поставщикам

Модель может обслуживаться несколькими эндпоинтами (маршрутами к поставщикам). GET /v1/models/{model} перечисляет их в endpoints: метка, цена, время до первого токена, скорость и статус. По умолчанию они используются по приоритету с балансировкой, а при сбое запрос переходит на следующий эндпоинт — до ваших резервных models[]. Сбоящие эндпоинты автоматически пропускаются ~30 с.

Управляйте этим через объект provider: order / only / ignore принимают метки эндпоинтов; sort упорядочивает по цене, скорости или задержке (:floor и :nitro делают то же); max_price ({ prompt, completion } в USD за 1M токенов, которые платите вы) пропускает более дорогие эндпоинты и возвращает 400 no_endpoints_match, если ничего не осталось; preferred_max_latency (секунды) и preferred_min_throughput (токенов/с) отодвигают медленные эндпоинты назад; allow_fallbacks: false — только первый. Имена, не совпадающие с метками модели, а также require_parameters, data_collection, quantizations и zdr передаются в OpenRouter для моделей, которые он обслуживает. Заголовок ответа x-ultragpt-endpoint и поля генерации provider_endpoint и route показывают, что было использовано и почему.

Python
response = client.chat.completions.create(
    model="grok-4.7",
    messages=messages,
    extra_body={
        "provider": {
            "sort": "price",               # or "throughput" / "latency"
            "order": ["primary"],          # endpoint labels from GET /v1/models/grok-4.7
            "ignore": ["backup-2"],
            "max_price": {"prompt": 3, "completion": 15},  # USD per 1M tokens you pay
            "allow_fallbacks": True,
            "data_collection": "deny",     # OpenRouter-served: only providers that don't train on data
            "zdr": True,                   # OpenRouter-served: zero data retention
        },
    },
)
# Which endpoint answered: response header x-ultragpt-endpoint,
# and GET /v1/generation?id=... -> provider_endpoint, route

Кэширование промптов

Токены из кэша оплачиваются по (намного меньшей) цене кэша из карточки модели. Модели OpenAI и DeepSeek кэшируют повторяющиеся префиксы автоматически; для Anthropic и Gemini отметьте стабильную часть через cache_control. Попадания видны в usage.prompt_tokens_details.cached_tokens.

Python
# Mark a large, stable prefix as cacheable (Anthropic / Gemini models via OpenRouter;
# OpenAI and DeepSeek models cache automatically). Cached tokens bill at the cached price.
response = client.chat.completions.create(
    model="grok-4.7",
    messages=[
        {"role": "system", "content": [
            {"type": "text", "text": LONG_REFERENCE_DOCUMENT, "cache_control": {"type": "ephemeral"}},
        ]},
        {"role": "user", "content": "Summarize section 3."},
    ],
)
print(response.usage.prompt_tokens_details.cached_tokens)

Резервные модели

Передайте до двух резервных моделей в models. Если основная модель не ответила по вине поставщика (сбой, перегрузка, таймаут), запрос повторяется на следующей — поле model в ответе покажет, какая ответила. Некорректные запросы (400) не повторяются.

curl https://api.ultragpt.pro/v1/chat/completions \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "models": ["<fallback-model-1>", "<fallback-model-2>"],
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'

Пресеты

Сохраните модель, резервные модели, системный промпт, параметры, маршрутизацию, плагины и кэш на странице «Пресеты» и вызывайте из любого текстового эндпоинта как model: "@preset/{slug}" (или "{model}@preset/{slug}", или "preset": "{slug}"). Поля запроса важнее пресета; инструменты и плагины объединяются. Правки создают версии с откатом — запросы всегда используют последнюю, так что промпты меняются без деплоя.

curl https://api.ultragpt.pro/v1/chat/completions \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "@preset/support-bot", "messages": [{ "role": "user", "content": "Hi" }] }'

# List the workspace's presets
curl https://api.ultragpt.pro/v1/presets -H "Authorization: Bearer $ULTRAGPT_API_KEY"

Кэш ответов

Отправьте X-UltraGPT-Cache: true (X-OpenRouter-Cache тоже работает) — и одинаковый запрос с того же ключа в течение TTL (X-UltraGPT-Cache-TTL, 1–86400 с, по умолчанию 300) вернётся из кэша мгновенно и бесплатно: счётчики usage равны 0, оплаты нет. Работает со стримингом и без, для chat, messages, responses и completions. Ответ содержит x-ultragpt-cache-status (HIT / MISS), -age, -ttl и -source-id; X-UltraGPT-Cache-Clear: true обновляет запись. Пресеты могут включать кэш для всех запросов.

curl -i https://api.ultragpt.pro/v1/chat/completions \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-UltraGPT-Cache: true" \
  -H "X-UltraGPT-Cache-TTL: 600" \
  -d '{ "model": "grok-4.7", "messages": [{ "role": "user", "content": "Capital of France?" }] }'

# Second identical call within 10 minutes:
# x-ultragpt-cache-status: HIT   x-ultragpt-cache-age: 12   usage.cost: 0
# Force a refresh: -H "X-UltraGPT-Cache-Clear: true"

Плагины, варианты и страховка

response-healing чинит битый JSON (блоки кода, лишние запятые, ключи без кавычек, недостающие скобки) в запросах json_object / json_schema без стриминга. context-compression убирает сообщения из середины диалога (сохраняя системные промпты, последний ход и пары вызов–результат инструментов), если промпт больше окна модели — по умолчанию для моделей с окном до 8K; x-ultragpt-compressed-messages показывает, сколько убрано. Суффиксы модели выбирают маршрут: :nitro быстрейший, :floor дешевле всего, :exacto надёжный вызов инструментов, :thinking рассуждения. Страховка пустого ответа: запрос без выходных токенов (пустой или упавший до начала ответа) не оплачивается; поток, оборвавшийся посередине, оплачивается за уже отданную часть.

Code
response = client.chat.completions.create(
    model="grok-4.7:nitro",          # :nitro fastest, :floor cheapest, :exacto best tool calling,
                                     # :thinking reasoning on, :online web search
    messages=long_conversation,
    response_format={"type": "json_object"},
    extra_body={
        "plugins": [
            {"id": "response-healing"},      # repair malformed JSON (non-streaming)
            {"id": "context-compression"},   # drop middle messages if over the context window
        ],
        "safety_identifier": "user-123",     # your end user (shows in /activity?user=)
    },
    extra_headers={"X-Client-Request-Id": "order-42"},  # echoed back + stored on the generation
)

Эмбеддинги

POST /embeddings принимает строку или до 2048 строк (или массивов токенов), с необязательными dimensions и encoding_format. Оплата за входные токены.

curl https://api.ultragpt.pro/v1/embeddings \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "qwen3-embedding-8b", "input": "The quick brown fox" }'

Генерация изображений

POST /images/generations с prompt, n (1–4) и response_format (b64_json или url), плюс параметры, которые поддерживает модель: aspect_ratio, resolution (1K/2K/4K), size, quality, background, output_format, output_compression, moderation и seed. GET /models/{model} перечисляет их в блоке images (aspect_ratios, resolutions, sizes, qualities, backgrounds, output_formats, seed, max_input_images); неподдерживаемый параметр вернёт 400 с param, а не тихое значение по умолчанию, а ответ повторяет применённые параметры. Мультимодальные модели также принимают image: [urls] для редактирования или файлы в POST /images/edits (multipart image / image[], как images.edit() в OpenAI SDK; mask не поддерживается). Если часть из n изображений не удалась, вы получаете и оплачиваете только удавшиеся. Оплата по стоимости поставщика.

curl https://api.ultragpt.pro/v1/images/generations \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "grok-imagine-image-2.0", "prompt": "A lighthouse at dawn, watercolor", "response_format": "url" }'

Синтез и распознавание речи

POST /audio/speech возвращает аудио (mp3, opus, aac, flac, wav, pcm) одним из голосов модели, цена за символ. POST /audio/transcriptions (и /audio/translations) принимают файл до 25 МБ и возвращают json, text, verbose_json, srt или vtt.

curl https://api.ultragpt.pro/v1/audio/speech \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "ai-voice", "voice": "default", "input": "Hello from UltraGPT!" }' \
  --output hello.mp3
curl https://api.ultragpt.pro/v1/audio/transcriptions \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -F model="audio-transcribe" \
  -F file="@meeting.mp3"

Batch API

Загрузите JSONL до 5000 запросов /v1/chat/completions или /v1/embeddings, создайте пакет и заберите файл с результатами в течение 24 часов — вне поминутных лимитов, не дороже обычной цены. Отменённые или просроченные пакеты возвращают выполненные строки. По завершении приходит вебхук batch.completed / batch.failed.

curl https://api.ultragpt.pro/v1/files -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -F purpose="batch" -F file="@requests.jsonl"

curl https://api.ultragpt.pro/v1/batches -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input_file_id": "file-...", "endpoint": "/v1/chat/completions", "completion_window": "24h" }'

Rerank, модерация и поиск

POST /rerank упорядочивает до 1000 документов по релевантности запросу (совместимо с Cohere; оплата за search unit). POST /moderations проверяет текст и изображения моделями модерации OpenAI — бесплатно. POST /search/{engine} выполняет веб-поиск через Tavily, Exa, Perplexity, Parallel или DataForSEO и возвращает title, url, snippet и текст страницы, оплата за запрос. GET /models?type=rerank|moderation|search покажет их с ценами.

# Rerank documents for RAG
curl https://api.ultragpt.pro/v1/rerank -H "Authorization: Bearer $ULTRAGPT_API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "cohere-rerank-v3.5", "query": "capital of France", "documents": ["Paris is...", "Berlin is..."], "top_n": 1 }'

# Moderate text or images (free)
curl https://api.ultragpt.pro/v1/moderations -H "Authorization: Bearer $ULTRAGPT_API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "omni-moderation-latest", "input": "text to check" }'

# Standalone web search (billed per query)
curl https://api.ultragpt.pro/v1/search/dataforseo-search -H "Authorization: Bearer $ULTRAGPT_API_KEY" -H "Content-Type: application/json" \
  -d '{ "query": "latest AI news", "max_results": 5 }'

Генерация видео

POST /videos запускает генерацию видео из текста или изображения в формате OpenAI Videos API и возвращает объект video (status queued). Опрашивайте GET /videos/{id} до completed (или failed), затем скачайте GET /videos/{id}/content — редирект на MP4 (?variant=thumbnail — обложка). Передайте seconds и aspect_ratio или size ("1280x720"); resolution и image_url (публичный https первый кадр) — если модель поддерживает. GET /models?type=video покажет длительности, пропорции и цену за секунду. Списывается фактическая стоимость у поставщика по завершении; неудачные ролики бесплатны. По завершении приходит вебхук video.completed / video.failed.

curl https://api.ultragpt.pro/v1/videos \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "seedance-2-0-mini", "prompt": "A paper boat in the rain", "seconds": 4, "size": "1280x720" }'

curl https://api.ultragpt.pro/v1/videos/video_... -H "Authorization: Bearer $ULTRAGPT_API_KEY"
curl -L https://api.ultragpt.pro/v1/videos/video_.../content -H "Authorization: Bearer $ULTRAGPT_API_KEY" -o clip.mp4

Голос в реальном времени

Откройте WebSocket к /realtime?model=<id> (wss://) и используйте протокол OpenAI Realtime: session.update, input_audio_buffer.append, response.create… Аутентификация — заголовок Authorization или, из браузера, подпротокол openai-insecure-api-key.<key> (только с ключом, ограниченным вашим доменом). Каждый ответ оплачивается по расходу, который сообщает модель; для расшифровки входа поддерживаются gpt-4o-transcribe, gpt-4o-mini-transcribe и whisper-1. Сессия закрывается через 60 минут, после 10 минут тишины или когда закончатся баланс или лимит ключа (событие error, затем код закрытия 1008).

import WebSocket from 'ws'

const ws = new WebSocket('wss://api.ultragpt.pro/v1/realtime?model=gpt-realtime', {
  headers: { Authorization: `Bearer ${process.env.ULTRAGPT_API_KEY}` },
})

ws.on('open', () => {
  ws.send(JSON.stringify({
    type: 'session.update',
    session: { instructions: 'Be brief.', voice: 'alloy' },
  }))
  ws.send(JSON.stringify({ type: 'response.create', response: { modalities: ['text'] } }))
})
ws.on('message', (data) => {
  const event = JSON.parse(data.toString())
  if (event.type === 'response.done') console.log(event.response.usage)
})

Идемпотентные повторы

Передавайте заголовок Idempotency-Key в платных POST-запросах. Повтор с тем же ключом и телом возвращает первый ответ (заголовок idempotent-replayed: true), без повторного выполнения и оплаты; повтор во время выполнения первого получает 409. Ключи хранятся 24 часа для каждого API-ключа.

curl https://api.ultragpt.pro/v1/chat/completions \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -H "Idempotency-Key: order-1234-summary" \
  -H "Content-Type: application/json" \
  -d '{ "model": "grok-4.7", "messages": [{ "role": "user", "content": "Hello!" }] }'

Атрибуция приложений

По желанию передавайте X-Title (название приложения) и HTTP-Referer (его URL). Так использование делится по приложениям.

curl https://api.ultragpt.pro/v1/chat/completions \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" \
  -H "X-Title: My App" \
  -H "HTTP-Referer: https://myapp.com" \
  ...

Ключ, баланс и генерации

GET /key возвращает лимиты и расходы ключа; GET /credits — баланс; GET /generation?id= — токены (включая кэш и рассуждения), стоимость, время до первого токена и задержку любого запроса.

# The calling key: rate limits, this month's spend
curl https://api.ultragpt.pro/v1/key -H "Authorization: Bearer $ULTRAGPT_API_KEY"

# Credit balance (shared with the UltraGPT app)
curl https://api.ultragpt.pro/v1/credits -H "Authorization: Bearer $ULTRAGPT_API_KEY"

# Tokens, cost and latency of one request, by its response id
curl "https://api.ultragpt.pro/v1/generation?id=chatcmpl-..." -H "Authorization: Bearer $ULTRAGPT_API_KEY"

Ключи управления и активность

Создайте ключ со scope "management", чтобы выдавать ключи из своего бэкенда — по одному на клиента, со своим лимитом расходов (limit + limit_reset: день, неделя, месяц или без сброса), списком моделей и лимитами запросов — через /keys, и управлять пресетами через /presets. Ключи управления не вызывают модели. GET /activity возвращает расход по дням, моделям и эндпоинтам за 30 дней (всё пространство для ключа управления, иначе — только этот ключ), с фильтрами по дате, ключу и пользователю. POST /generations/lookup возвращает точную стоимость до 1000 запросов сразу — удобно для выставления счетов своим клиентам.

# With a management key: provision a key per customer, capped at $20/month
curl https://api.ultragpt.pro/v1/keys -H "Authorization: Bearer $ULTRAGPT_MANAGEMENT_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "customer-42", "limit": 20, "allowed_models": ["gpt-5-mini"], "rpm_limit": 60 }'
# -> { "data": { "id": "...", "limit_remaining": 20, ... }, "key": "ugpt_live_..." }  (shown once)

curl https://api.ultragpt.pro/v1/keys -H "Authorization: Bearer $ULTRAGPT_MANAGEMENT_KEY"              # list
curl -X PATCH https://api.ultragpt.pro/v1/keys/KEY_ID -d '{ "limit": 50 }' ...                         # update
curl -X DELETE https://api.ultragpt.pro/v1/keys/KEY_ID -H "Authorization: Bearer $ULTRAGPT_MANAGEMENT_KEY"  # revoke

# Daily usage per model for the last 30 days (?date=, ?key_id=, ?user=)
curl https://api.ultragpt.pro/v1/activity -H "Authorization: Bearer $ULTRAGPT_MANAGEMENT_KEY"

# Exact cost of up to 1000 requests at once (any key, incl. read-only)
curl https://api.ultragpt.pro/v1/generations/lookup -H "Authorization: Bearer $ULTRAGPT_API_KEY" -H "Content-Type: application/json" \
  -d '{ "ids": ["chatcmpl-...", "chatcmpl-..."] }'

Вебхуки

Настройте HTTPS-эндпоинт в Настройках для событий balance.low, credits.added, key.created / rotated / revoked, key.spend_cap.warning / reached, key.expiring, account.daily_limit.reached, batch.completed / failed, video.completed / failed и model.deprecated. Каждый POST — JSON { id, type, created, data } с подписью HMAC-SHA256.

Неудачная доставка (не 2xx или таймаут) повторяется через 30 секунд, 5 минут и 30 минут с тем же id события — используйте его для дедупликации. Повторы переживают наши перезапуски. Все попытки видны в настройках, где любое событие можно отправить заново. После 20 неудач подряд вебхук приостанавливается.

import crypto from 'node:crypto'

// UltraGPT-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
export function verifyWebhook(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')))
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex')
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < toleranceSec
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ''))
}

Журналы, аудит и безопасность

По умолчанию промпты и ответы не сохраняются. Включите журнал запросов в Настройках , чтобы хранить их в зашифрованном виде 1–30 дней и видеть в деталях каждого запроса в разделе «Активность» (встроенные изображения заменяются заглушкой); удалить их можно в любой момент.

Журнал аудита в настройках показывает, кто создавал, перевыпускал или отзывал ключи и менял вебхук, ключи поставщиков, настройки, пресеты и участников организации — с IP и временем; владелец и админы организации видят журнал всей команды.

Включите подтверждение по email (Настройки > Безопасность), чтобы требовать 6-значный код перед созданием или перевыпуском ключей, выдачей scope management, сохранением вебхука или ключа поставщика и удалением организации. Подтверждение действует 15 минут.

Свой ключ (BYOK)

Добавьте свой ключ OpenRouter или OpenAI в настройках, и запросы к моделям этого поставщика пойдут через ваш аккаунт: вы платите поставщику, а мы берём небольшую комиссию. Если поставщик отклонит ключ, придёт ошибка byok_key_rejected.

Организации

Создайте организацию на странице Команда и пригласите людей по email. Ключи организации оплачиваются с баланса владельца; участники видят использование команды и управляют своими ключами; владелец и админы — всем. Переключайте пространства в боковой панели.

Оплата

Запросы оплачиваются за токены с предоплаченного баланса — никогда не из лимитов подписки. Перед запросом доступный баланс должен покрывать худший случай (вход плюс max_tokens, или 4096 выходных токенов, если не задано); списывается только фактический расход.

Лимиты

Лимиты запросов в минуту и одновременных запросов действуют на ключ и одинаковы для всех — без уровней. Дневной лимит расходов (аккаунт) и месячный (ключ) задаёте вы сами (см. Модели). Каждый ответ /v1 содержит x-ratelimit-limit-requests, x-ratelimit-remaining-requests и x-ratelimit-reset-requests; при 429 добавляется retry-after.

У каждого ключа также есть лимит токенов в минуту (вход + выход, заголовки x-ratelimit-*-tokens; ключ может только уменьшить его) и лимит расходов со сбросом каждый день, неделю (понедельник, UTC), месяц или без сброса — предоплаченный бюджет для одного клиента. GET /key показывает limit, limit_remaining и расход по периодам.

# A key for one customer: $20 per week, 30k tokens per minute
curl https://api.ultragpt.pro/v1/keys -H "Authorization: Bearer $ULTRAGPT_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "customer-42", "limit": 20, "limit_reset": "weekly", "tpm_limit": 30000 }'

# What the calling key has left
curl https://api.ultragpt.pro/v1/key -H "Authorization: Bearer $ULTRAGPT_API_KEY"
# -> { "data": { "limit": 20, "limit_reset": "weekly", "limit_remaining": 13.4,
#               "usage_daily": 1.2, "usage_weekly": 6.6, "usage_monthly": 18.1, ... } }

Ошибки

Ошибки в формате OpenAI { "error": { message, type, code, param } } (Anthropic — на /v1/messages), поэтому SDK выбрасывают привычные исключения.

400invalid_request_errorНекорректный запрос; `param` — поле. unsupported_parameter: модель не поддерживает инструменты / изображения.
401authentication_errorКлюч отсутствует, неверен, отозван или истёк.
402insufficient_quotaНедостаточно средств. Пополните баланс или уменьшите max_tokens.
403permission_errorКлюч только для чтения, IP / домен не разрешён, аккаунт ограничен, или management_key_required / ключ управления для вызова моделей.
404not_found_errorМодель не найдена (или недоступна ключу), или preset_not_found.
410model_retiredМодель снята с обслуживания и не имеет замены. В сообщении указано, что использовать.
409idempotency_conflictЗапрос с этим Idempotency-Key ещё выполняется.
429rate_limit_errorСлишком много запросов. Соблюдайте retry-after.
429rate_limit_errortokens_limit_exceeded: лимит токенов в минуту ключа. Соблюдайте retry-after.
429insufficient_quotaЛимит расходов ключа (daily_ / weekly_ / monthly_spend_cap_reached, key_limit_reached — общий лимит) или daily_spend_limit_reached аккаунта.
502 / 504api_errorВсе модели не ответили. Можно повторить.
403org_member_spend_capКлюч участника организации должен иметь лимит не выше лимита участников (дневной x31, недельный x5).
429rate_limit_errorЛимит аккаунта: слишком много запросов по всем ключам оплачивающего аккаунта.
503service_unavailableМодель временно недоступна.
400no_endpoints_matchprovider.max_price / only / ignore исключили все эндпоинты модели.
503model_circuit_openПоставщик модели сбоит, она пропускается ~30 с. Передайте запасные модели в models: [...]; соблюдайте retry-after.
503server_restartingСервер перезапускается. Запрос не выполнялся и не оплачивался — повторите.

Устаревание моделей

Когда модель планируется к отключению, каждый её ответ содержит заголовки Deprecation и Sunset (и x-ultragpt-model-replacement), каталог помечает её устаревшей, а аккаунты, использовавшие её за 30 дней, получают письмо, уведомление и вебхук model.deprecated — сразу и ещё раз за неделю. После даты отключения запросы к ней обслуживает замена (заголовок x-ultragpt-model-redirected-from) или они получают 410 model_retired. Следите за страницей статуса.

Code
curl -si https://api.ultragpt.pro/v1/chat/completions \
  -H "Authorization: Bearer $ULTRAGPT_API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "grok-4.7", "messages": [{ "role": "user", "content": "Hi" }] }' | grep -i -E "^(deprecation|sunset|link|x-ultragpt-model)"

# deprecation: @1790000000
# sunset: Thu, 15 Oct 2026 00:00:00 GMT
# x-ultragpt-model-replacement: newer-model
# After the sunset: answered by the replacement (x-ultragpt-model-redirected-from),
# or HTTP 410 { "error": { "code": "model_retired" } } when there is none.

Изменения

2026-10-12Маршрутизация по нескольким поставщикам: у модели может быть несколько эндпоинтов (GET /v1/models/{model} → endpoints) с автоматическим переключением, балансировкой и учётом их состояния. provider.order / only / ignore принимают метки эндпоинтов; provider.sort — по цене, скорости или задержке; provider.max_price (USD за 1M, которые платите вы) и preferred_max_latency / preferred_min_throughput. Заголовок x-ultragpt-endpoint; поля provider_endpoint, route, client_disconnected и aborted_on_disconnect в генерациях. X-UltraGPT-Abort-On-Disconnect: true останавливает стрим при отключении клиента и оплачивает только выданное.
2026-10-11POST /v1/images/edits (multipart, images.edit в OpenAI SDK). Страховка пустого ответа теперь как в OpenRouter: поток, оборвавшийся после начала ответа, оплачивается за отданную часть. При частичном успехе n изображений возвращаются и оплачиваются удавшиеся. Файлы, пакеты и списки видео разделены по рабочим пространствам ключа (личное или организация). Повтор по Idempotency-Key теперь работает для /v1/videos и учитывает загруженные файлы. Для новых видео баланс должен покрывать и ещё рендерящиеся ролики.
2026-10-03Спецификация OpenAPI со схемами ответов и operationId (также /v1/openapi.json) и коллекция Postman. POST /v1/files возвращает 200, как OpenAI; GET /v1/files с пагинацией (limit, after). Неверный limit — ошибка 400. Лимиты аккаунта по всем ключам, автоматическое отключение сбоящей модели (503 model_circuit_open), плавные обновления (503 server_restarting, можно повторять). Ключи участников организации ограничены лимитом владельца. Экспорт и удаление данных в «Настройки > Ваши данные». Статус в формате Statuspage summary.json.
2026-10-02/v1/videos (асинхронная генерация видео) и /v1/realtime (голос по WebSocket). Лимиты расходов ключа со сбросом каждый день, неделю, месяц или без сброса (limit / limit_reset) и лимит токенов в минуту. Устаревание моделей с заголовками Deprecation / Sunset и 410 model_retired. Новые вебхуки: credits.added, key.created / rotated / revoked, video.completed / failed, model.deprecated; неудачные доставки повторяются и после перезапуска, их можно отправить заново. Журнал запросов (по желанию), журнал аудита, подтверждение по email для важных действий, инциденты на странице статуса с RSS и email.
2026-10-01Пресеты (@preset/slug, с версиями), кэш ответов (бесплатные попадания), плагины response-healing и context-compression, варианты :nitro / :floor / :exacto / :thinking, страховка пустого ответа, /rerank, /moderations, /search, ключи управления (/keys), /activity, /generations/lookup, фильтры /models и /models/count, учёт safety_identifier и X-Client-Request-Id.
2026-09-30Anthropic Messages API, Responses API, legacy completions, эмбеддинги, изображения, синтез и распознавание речи, Files и Batch API, плагин веб-поиска, маршрутизация, Idempotency-Key, перевыпуск ключей, ограничения по IP / доменам, ключи только для чтения, вебхуки, BYOK, организации, дневные лимиты.
2026-09-29Резервные модели (models[]), /key, /credits, /generation, атрибуция приложений, расширенный /models.
2026-09-28Закрытое превью: /v1/chat/completions и /v1/models.