Документация
Совместимо с OpenAI и Anthropic. Укажите в любом SDK адрес https://api.ultragpt.pro/v1.
- Создайте API-ключ и сохраните его как
ULTRAGPT_API_KEY. - Пополните баланс (общий с приложением UltraGPT).
- Установите 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!" }]
}'Эндпоинты
/chat/completionsChat completion (формат OpenAI), со стримингом или без./messagesAnthropic Messages API (Anthropic SDK, Claude Code)./messages/count_tokensОценка числа токенов (формат Anthropic)./responsesOpenAI Responses API с хранением диалогов./responses/{id}Сохранённый ответ (также DELETE, /input_items)./completionsУстаревший text completions./embeddingsЭмбеддинги текста./images/generationsГенерация изображений./images/editsРедактирование загруженных изображений (multipart, images.edit в OpenAI SDK)./audio/speechСинтез речи./audio/transcriptionsРаспознавание речи (также /audio/translations)./filesЗагрузка файла для Batch (также GET, DELETE, /content)./batchesДо 5000 запросов асинхронно, вне лимитов запросов (также GET, /cancel)./rerankРанжирование документов по запросу (Cohere / Voyage / Qwen)./moderationsПроверка текста и изображений на вредный контент. Бесплатно./videosЗапуск генерации видео (асинхронно; также GET, GET /content, DELETE)./realtime?model=Голос в реальном времени по WebSocket (протокол OpenAI Realtime)./search/{engine}Отдельный веб-поиск (Tavily, Exa, Perplexity…), оплата за запрос./modelsМодели, доступные ключу (фильтры ?type=, ?supported_parameters=, ?input_modalities=; также /models/count)./presetsПресеты рабочего пространства (изменение — ключом управления)./keysКлючи управления: список, создание, изменение, отзыв ключей./activityРасход по дням, моделям и эндпоинтам за 30 дней./generations/lookupСтоимость и статистика до 1000 запросов сразу./keyТекущий ключ: лимиты, расходы./creditsБаланс и итоги./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:
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.
Надёжные запросы: резерв, повторы, без двойной оплаты
# 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-схеме
# 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)Точная стоимость для ваших клиентов
# 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
# 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
# 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).textChat 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 показывают, что было использовано и почему.
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.
# 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 рассуждения. Страховка пустого ответа: запрос без выходных токенов (пустой или упавший до начала ответа) не оплачивается; поток, оборвавшийся посередине, оплачивается за уже отданную часть.
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.mp3curl 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 выбрасывают привычные исключения.
invalid_request_errorНекорректный запрос; `param` — поле. unsupported_parameter: модель не поддерживает инструменты / изображения.authentication_errorКлюч отсутствует, неверен, отозван или истёк.insufficient_quotaНедостаточно средств. Пополните баланс или уменьшите max_tokens.permission_errorКлюч только для чтения, IP / домен не разрешён, аккаунт ограничен, или management_key_required / ключ управления для вызова моделей.not_found_errorМодель не найдена (или недоступна ключу), или preset_not_found.model_retiredМодель снята с обслуживания и не имеет замены. В сообщении указано, что использовать.idempotency_conflictЗапрос с этим Idempotency-Key ещё выполняется.rate_limit_errorСлишком много запросов. Соблюдайте retry-after.rate_limit_errortokens_limit_exceeded: лимит токенов в минуту ключа. Соблюдайте retry-after.insufficient_quotaЛимит расходов ключа (daily_ / weekly_ / monthly_spend_cap_reached, key_limit_reached — общий лимит) или daily_spend_limit_reached аккаунта.api_errorВсе модели не ответили. Можно повторить.org_member_spend_capКлюч участника организации должен иметь лимит не выше лимита участников (дневной x31, недельный x5).rate_limit_errorЛимит аккаунта: слишком много запросов по всем ключам оплачивающего аккаунта.service_unavailableМодель временно недоступна.no_endpoints_matchprovider.max_price / only / ignore исключили все эндпоинты модели.model_circuit_openПоставщик модели сбоит, она пропускается ~30 с. Передайте запасные модели в models: [...]; соблюдайте retry-after.server_restartingСервер перезапускается. Запрос не выполнялся и не оплачивался — повторите.Устаревание моделей
Когда модель планируется к отключению, каждый её ответ содержит заголовки Deprecation и Sunset (и x-ultragpt-model-replacement), каталог помечает её устаревшей, а аккаунты, использовавшие её за 30 дней, получают письмо, уведомление и вебхук model.deprecated — сразу и ещё раз за неделю. После даты отключения запросы к ней обслуживает замена (заголовок x-ultragpt-model-redirected-from) или они получают 410 model_retired. Следите за страницей статуса.
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.