# API Весело — нейросети по API за рубли MCP без ключа: https://veselo.ai/mcp — добавь этот адрес в Claude, Claude Code, Cursor или VS Code. Нейросеть откроет veselo.ai: человек входит и нажимает «Разрешить» (OAuth 2.1, PKCE). Как подключить: https://veselo.ai/docs/mcp. Базовый адрес API: https://veselo.ai/v1 (совместим с OpenAI). Ключ: заголовок Authorization: Bearer sk-vsl-… — выпускается на https://veselo.ai/developer. Документация для людей: https://veselo.ai/docs. Формат Anthropic (Claude Code, SDK Anthropic): адрес https://veselo.ai, метод POST https://veselo.ai/v1/messages, ключ — в x-api-key или Authorization; модели — текстовые, те же, что у чата, Claude нет. Как подключить: https://veselo.ai/docs/anthropic. # Быстрый старт: первый запрос за 3 минуты API нейросетей за рубли: выпусти ключ, пополни API-счёт картой или по СБП и отправь первый запрос к DeepSeek через curl, Python или JavaScript. API Весело совместим с OpenAI: подходит любая программа или библиотека, которая умеет звать OpenAI Chat Completions. Меняешь только адрес — `https://veselo.ai/v1` — и ключ. Платишь в рублях, VPN не нужен. Claude Code и SDK Anthropic тоже подходят: для них есть вход в формате Anthropic — [Claude Code и формат Anthropic](https://veselo.ai/docs/anthropic). 1. Войди на veselo.ai и выпусти ключ в кабинете [API](https://veselo.ai/developer). Сохрани его сразу; посмотреть ключ снова можно в кабинете, подтвердив кодом. 2. Пополни API-счёт в [кабинете](https://veselo.ai/developer/wallet) картой или по СБП. Это отдельный счёт — только для запросов по ключу, от 100 ₽. 3. Положи ключ в переменную окружения `VESELO_API_KEY` — так его не придётся вставлять в код. 4. Отправь запрос на `https://veselo.ai/v1/chat/completions` с заголовком `Authorization: Bearer <ключ>`. macOS и Linux: ```bash export VESELO_API_KEY="sk-vsl-…" ``` Windows PowerShell: ```text $env:VESELO_API_KEY = "sk-vsl-…" ``` curl: ```bash curl https://veselo.ai/v1/chat/completions \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek/deepseek-v4.1-flash-ultrafast", "max_tokens": 300, "messages": [{"role": "user", "content": "Объясни в двух предложениях, что такое API."}] }' ``` Python: ```python import os from openai import OpenAI # pip install openai client = OpenAI(base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"]) r = client.chat.completions.create( model="deepseek/deepseek-v4.1-flash-ultrafast", messages=[{"role": "user", "content": "Объясни в двух предложениях, что такое API."}], max_tokens=300, ) print(r.choices[0].message.content) print("Цена:", r.usage.cost_rub, "₽") ``` JavaScript: ```js // hello.mjs, запуск: node hello.mjs import OpenAI from 'openai'; // npm i openai const client = new OpenAI({ baseURL: 'https://veselo.ai/v1', apiKey: process.env.VESELO_API_KEY }); const r = await client.chat.completions.create({ model: 'deepseek/deepseek-v4.1-flash-ultrafast', messages: [{ role: 'user', content: 'Объясни в двух предложениях, что такое API.' }], max_tokens: 300, }); console.log(r.choices[0].message.content); console.log('Цена:', r.usage.cost_rub, '₽'); ``` Ответ: ```json { "id": "chatcmpl-req_5b2e9c0d41f84a7f9e3c2a1b0d6f8e47", "object": "chat.completion", "created": 1794132000, "model": "deepseek/deepseek-v4.1-flash-ultrafast", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "API — это правила, по которым одна программа обращается к другой. Например, твой код отправляет текст нейросети и получает ответ." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 19, "completion_tokens": 41, "total_tokens": 60, "cost_rub": 0.01 } } ``` Текст ответа — в `choices[0].message.content`, цена запроса в рублях — в `usage.cost_rub` и в заголовке `x-veselo-cost-rub`. Запрос, который закончился ошибкой, не стоит денег. ## Что дальше - [Модели](https://veselo.ai/docs/models) — какие модели есть и сколько стоят. - [Цены и списания](https://veselo.ai/docs/pricing) — как устроен API-счёт и зачем ставить `max_tokens`. - [Стриминг](https://veselo.ai/docs/streaming) — ответ по кусочкам, как в чате. - [Ошибки](https://veselo.ai/docs/errors) — что повторять, а что нет. - [Ключ для нейросети](https://veselo.ai/docs/agents) — как подключить API к ИИ-агенту. Вся документация одним файлом — [llms.txt](https://veselo.ai/docs/llms.txt). --- # Ключи и авторизация Ключ API Весело: где выпустить, как передать в заголовке Authorization, месячный лимит расхода, отзыв ключа и правила безопасности. Каждый запрос к API подписывается ключом. Ключ выглядит так: `sk-vsl-` и ещё 43 латинские буквы и цифры. Выпускается в кабинете [veselo.ai/developer](https://veselo.ai/developer). > ИИ-помощнику — Claude, Claude Code, Cursor, VS Code — ключ не нужен: он подключается к [MCP-серверу](https://veselo.ai/docs/mcp#no-key), а ты входишь на veselo.ai и нажимаешь «Разрешить». ## Как передать ключ В заголовке `Authorization: Bearer sk-vsl-…` — так делают SDK OpenAI и большинство программ. Если программа умеет только `x-api-key`, подойдёт и он: `x-api-key: sk-vsl-…`. Если переданы оба, берётся `Authorization`. Проверить ключ проще всего запросом баланса — он бесплатный: curl: ```bash curl https://veselo.ai/v1/balance -H "Authorization: Bearer $VESELO_API_KEY" ``` Python: ```python import os import requests # pip install requests r = requests.get( "https://veselo.ai/v1/balance", headers={"Authorization": f"Bearer {os.environ['VESELO_API_KEY']}"}, timeout=30, ) print(r.status_code, r.json()) ``` JavaScript: ```js const res = await fetch('https://veselo.ai/v1/balance', { headers: { Authorization: `Bearer ${process.env.VESELO_API_KEY}` }, }); console.log(res.status, await res.json()); ``` Ответ 200 — ключ работает. 401 — ключа нет, он с ошибкой или отозван; что в ответе, описано в разделе [Справочник](https://veselo.ai/docs/reference#balance). ## Как устроены ключи - Ключ целиком показывается при выпуске. Посмотреть его снова можно в [кабинете](https://veselo.ai/developer): значок глаза у ключа, код подтверждения придёт в чат с ботом (Telegram, VK) или на почту для входа. Ключи, выпущенные до 8 ноября 2026 года, так не показать — только выпустить новый. - В списке ключ узнаётся по имени, первым знакам и последним четырём. - Действующих ключей — до 20, новых можно выпустить до 10 в час. - Ключу можно задать месячный лимит расхода — от 1 до 1 000 000 ₽ или без лимита. Месяц считается по московскому времени. - Отзыв срабатывает сразу: следующий запрос с отозванным ключом получит 401. Отозванный ключ не восстанавливается. - Деньги у всех ключей общие — API-счёт аккаунта. `GET /v1/balance` и `GET /v1/usage` показывают баланс и расход всего аккаунта, а не одного ключа. ## Месячный лимит ключа Лимит защищает от лишних трат, если ключ утёк или программа зациклилась. Перед каждым запросом складываются: потраченное ключом за месяц, удержания его идущих запросов и удержание нового запроса. Если сумма больше лимита, ответ — 403 `key_limit_reached` с полями `limit_rub` и `spent_rub`. > Лимит сравнивается с удержанием — наибольшей ценой запроса, а не с фактической. При маленьком лимите ставь `max_tokens`: без него запрос удерживает цену 16 384 токенов ответа и может не пройти даже в начале месяца. Подробнее — [Цены и списания](https://veselo.ai/docs/pricing#hold). ## Ошибки ключа | HTTP | code | Когда | |---|---|---| | 401 | `missing_api_key` | ключа нет в запросе | | 401 | `invalid_api_key` | ключ с ошибкой, отозван или не найден | | 403 | `account_blocked` | аккаунт заблокирован — не работает ни один его ключ | | 403 | `key_limit_reached` | запрос не помещается в месячный лимит ключа | ## Безопасность - Храни ключ в переменной окружения или хранилище секретов, не в коде. Не коммить его в git. - Не вставляй ключ в код сайта или мобильного приложения: его увидит любой. Зови API со своего сервера. - Заводи отдельный ключ на каждую программу и ИИ-агента: так видно, кто сколько тратит, и отозвать можно точечно. - Ставь месячный лимит ключам, которые отдаёшь агентам и скриптам. - Ключ утёк — отзови его в [кабинете](https://veselo.ai/developer) и выпусти новый. - В журналах нашего сервера ключ вырезается. --- # Цены и списания Сколько стоит API нейросетей в рублях: цена за 1 млн токенов, API-счёт и его пополнение, кэшбэк до 5%, удержание на время запроса и примеры расчёта. Платишь только за запросы — по ценам модели, в рублях. Абонентской платы нет. ## Из чего складывается цена Текстовые модели считают текст в токенах. Токен — кусок слова: в русском тексте обычно 2–4 знака. Цена модели — в рублях за 1 млн токенов, отдельно за вход (что ты отправляешь, вместе с историей диалога) и выход (что пишет модель). Выход обычно дороже. | Поле в pricing_rub | За что | |---|---| | `input_per_1m` | 1 млн токенов входа | | `output_per_1m` | 1 млн токенов выхода, включая рассуждения у моделей, которые думают перед ответом | | `cached_input_per_1m` | 1 млн токенов входа, взятых из кэша модели, — например, повторённое начало длинного диалога. Есть не у всех моделей | | `per_request` | сам запрос — у некоторых моделей | | `per_image_input` | картинка во входе — у некоторых моделей | | `per_image` | картинка на выходе, 1 МП; цена от — подробнее в разделе «Картинки» | | `per_image_quality` | картинка нейросетью Студии по качеству: `{"1K": …, "2K": …, "4K": …}` — раздел [Картинки](https://veselo.ai/docs/images) | | `per_video` | ролик по качеству и длине: `per_video["720p"]["10"]` — раздел [Видео](https://veselo.ai/docs/video) | | `per_speech` | озвучка текста до стольких знаков: `per_speech["2000"]` — раздел [Озвучка](https://veselo.ai/docs/speech) | | `per_track` | музыкальный трек — раздел [Музыка](https://veselo.ai/docs/music) | Цены — в `GET https://veselo.ai/v1/models` и на странице [Модели](https://veselo.ai/models); по ним же идёт списание. Цены могут меняться, актуальные — всегда в списке моделей. Цена каждого запроса округляется вверх до копейки. Точная цена приходит в ответе: поле `usage.cost_rub` и заголовок `x-veselo-cost-rub`. Она может немного отличаться от расчёта по прайсу — например, вход из кэша дешевле. Вход из кэша считается по цене `cached_input_per_1m`, остальной вход — по `input_per_1m`. Сколько токенов входа модель взяла из кэша, видно в ответе: `usage.prompt_tokens_details.cached_tokens` — они входят в `usage.prompt_tokens`. За день — поле `cached_input_tokens` в `GET /v1/usage`. ## API-счёт У API свой счёт в копейках: запрос к текстовой модели часто стоит меньше копейки. Это отдельный счёт — только для запросов по ключу, он не связан с основным балансом veselo.ai, с которого оплачиваются ролики. - **Пополнение.** В [кабинете](https://veselo.ai/developer/wallet): картой или по СБП, T-Pay, SberPay, от 100 до 15 000 ₽ за раз. Сколько оплачено — столько и пришло, бонусов к пополнению нет. - **Без переводов.** Деньги между API-счётом и основным балансом не переводятся — ни туда, ни обратно. - **Не хватает.** Тратится только то, что лежит на API-счёте: когда не хватит, придёт ошибка 402 со ссылкой на пополнение. - **Возврат.** Неизрасходованные оплаченные деньги можно вернуть по [условиям API](https://veselo.ai/legal/api) — напиши в поддержку. ## Кэшбэк до 5% Чем больше потратишь за месяц, тем больше вернём — 1-го числа следующего месяца, на API-счёт. Процент — от всего расхода месяца по московскому времени. | Расход за месяц | Кэшбэк | |---|---| | от 100 ₽ | 1% | | от 1 000 ₽ | 2% | | от 5 000 ₽ | 3% | | от 20 000 ₽ | 4% | | от 50 000 ₽ | 5% | Например, за месяц потрачено 6 120 ₽ — это ступень 3%, 1-го числа на API-счёт придёт 183,60 ₽. Кэшбэк тратится первым и деньгами не возвращается. Сколько потрачено в этом месяце и сколько вернём — в [кабинете](https://veselo.ai/developer/wallet). ## Удержание на время запроса Сколько напишет модель, заранее неизвестно. Поэтому перед запросом на счёте удерживается его наибольшая цена, а после ответа удержание снимается и списывается фактическая. Разница сразу снова доступна. - Вход оценивается по длине текста сообщений с запасом — примерно токен на каждые 2 знака. Картинка — как 1500 токенов плюс её цена, если она есть у модели. - Выход — по `max_tokens` (или `max_completion_tokens`). Без него — 16 384 токена или меньше, если модель столько не пишет. - Не хватает на удержание — ошибка 402 `insufficient_balance` с полями `required_rub` (сколько нужно), `available_rub` (сколько есть) и `topup_url` (где пополнить). - Если ответ вышел дороже удержания (вход оказался длиннее оценки), разница всё равно списывается. Счёт может ненадолго уйти в небольшой минус — следующее пополнение сначала покроет минус. > Ставь `max_tokens` с запасом под ожидаемый ответ: удержание станет меньше, и при том же балансе одновременно пройдёт больше запросов. На цену это не влияет — платишь за то, что модель написала. Только не ставь его больше `max_output_tokens` модели: удержание считается по твоему числу. ## Примеры расчёта Цены в примерах условные: вход — 40 ₽, выход — 120 ₽ за 1 млн токенов. Настоящие — в [списке моделей](https://veselo.ai/docs/models). | Запрос | Удержание | Списание | |---|---|---| | Короткий вопрос на 50 токенов, ответ 300 токенов, без `max_tokens` | ≈ 1,97 ₽: 16 384 токена ответа × 120 ₽ за 1 млн | 0,04 ₽ | | Тот же вопрос с `max_tokens: 500` | ≈ 0,07 ₽ | 0,04 ₽ | | Документ на 60 000 знаков (≈ 20 000 токенов), ответ 1000 токенов, `max_tokens: 2000` | ≈ 1,44 ₽: вход оценён с запасом как 30 000 токенов | 0,92 ₽ | | Десятый вопрос в диалоге: история 8000 токенов, ответ 400, `max_tokens: 1000` | ≈ 0,60 ₽ | 0,37 ₽ | Например, первая строка: 50 × 40 ₽ / 1 млн + 300 × 120 ₽ / 1 млн = 0,038 ₽, вверх до копейки — 0,04 ₽. API не помнит прошлых сообщений, поэтому в диалоге каждый запрос оплачивает всю историю заново. Длинный диалог дешевле, если сокращать или пересказывать его старую часть. ## Когда деньги не списываются - Запрос закончился ошибкой — любой из [кодов ошибок](https://veselo.ai/docs/errors): удержание снимается целиком. - Исключение — поток, оборванный посреди ответа: списывается то, что модель успела сгенерировать. Так бывает, если программа закрыла соединение или модель замолчала. - Запрос без стриминга дорабатывает до конца, даже если программа перестала ждать ответ, и оплачивается. Поэтому не ставь тайм-аут клиента меньше 5 минут — или включай `stream: true`. ## Как следить за расходом - Цена запроса — `usage.cost_rub` в ответе (в потоке — в последнем куске) и заголовок `x-veselo-cost-rub`. - Сколько можно потратить сейчас — заголовок `x-veselo-balance-rub` и `GET /v1/balance`. - Расход по дням и моделям — `GET /v1/usage?days=30` и кабинет [veselo.ai/developer](https://veselo.ai/developer). - Чтобы ограничить траты одной программы, поставь её ключу [месячный лимит](https://veselo.ai/docs/auth#limit). Python: ```python import os from openai import OpenAI client = OpenAI(base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"]) spent = 0.0 for q in ["Столица Франции?", "Сколько будет 17 × 23?"]: r = client.chat.completions.create( model="deepseek/deepseek-v4.1-flash-ultrafast", messages=[{"role": "user", "content": q}], max_tokens=100, ) spent += r.usage.cost_rub print(q, "→", r.choices[0].message.content) print(f"Потрачено: {spent:.2f} ₽") ``` curl: ```bash curl "https://veselo.ai/v1/usage?days=7" -H "Authorization: Bearer $VESELO_API_KEY" ``` --- # Модели и цены Список моделей API с ценами в рублях: DeepSeek, Qwen, Kimi, GLM, Llama и другие. Как получить id модели и выбрать подходящую. Модель задаётся полем `model` — это id вида `vendor/model`, например `deepseek/deepseek-v4.1-flash-ultrafast`. Список моделей с ценами в рублях отдаёт `GET https://veselo.ai/v1/models` — без ключа. Актуальный список моделей с ценами в рублях: `GET https://veselo.ai/v1/models` (без ключа) или https://veselo.ai/models. ## Поля модели | Поле | Что это | |---|---| | `id` | что писать в `model` | | `name` | название | | `owned_by` | создатель модели — первая часть id | | `type` | тип модели: `text`, `image` или `video` | | `context_length` | сколько токенов модель читает за раз — вход и ответ вместе; может быть `null` | | `max_output_tokens` | сколько токенов модель может написать в одном ответе; может быть `null` | | `input_modalities` | что модель принимает на вход: `text`, у некоторых ещё `image` — см. [Картинки во входе](https://veselo.ai/docs/vision) | | `output_modalities` | что модель отдаёт: `text`, `image` или `video` | | `pricing_rub` | цены в рублях — см. [Цены и списания](https://veselo.ai/docs/pricing#price) | | `supported_parameters` | какие параметры модель понимает: `tools`, `response_format`, `reasoning` и другие | | `image` | у картинок: `aspect_ratios`, `max_n`, `output_formats` — см. [Картинки](https://veselo.ai/docs/images) | | `created` | когда модель появилась в каталоге, Unix-время | | `providers` | кто обслуживает модель: код для выбора, цена в рублях, хранит ли запросы — см. [Провайдеры](https://veselo.ai/docs/providers) | | `routing` | кого запрос без выбора пробует первым: `cheapest` — самого дешёвого, `fastest` — самого быстрого (не дороже цены модели) | curl: ```bash curl -s https://veselo.ai/v1/models | jq -r '.data[] | [.id, .pricing_rub.input_per_1m, .pricing_rub.output_per_1m] | @tsv' ``` Python: ```python import requests # pip install requests models = requests.get("https://veselo.ai/v1/models", timeout=30).json()["data"] # 10 самых дешёвых по выходу моделей, которые умеют вызывать функции with_tools = [m for m in models if "tools" in m["supported_parameters"] and "output_per_1m" in m["pricing_rub"]] for m in sorted(with_tools, key=lambda m: m["pricing_rub"]["output_per_1m"])[:10]: p = m["pricing_rub"] print(f'{m["id"]}: вход {p.get("input_per_1m")} ₽, выход {p["output_per_1m"]} ₽ за 1 млн, контекст {m["context_length"]}') ``` JavaScript: ```js const { data } = await (await fetch('https://veselo.ai/v1/models')).json(); // модели, которые читают картинки for (const m of data.filter((m) => m.input_modalities.includes('image'))) { console.log(m.id, m.pricing_rub.input_per_1m, m.pricing_rub.output_per_1m); } ``` Ответ: ```json { "object": "list", "data": [ { "id": "deepseek/deepseek-v4.1-flash-ultrafast", "object": "model", "created": 1735689600, "owned_by": "deepseek", "name": "DeepSeek V4.1 Flash Ultrafast", "type": "text", "context_length": 1048576, "max_output_tokens": 16384, "input_modalities": ["text"], "output_modalities": ["text"], "pricing_rub": { "input_per_1m": 40, "output_per_1m": 120 }, "supported_parameters": ["max_tokens", "temperature", "top_p", "stop", "seed", "tools", "tool_choice", "response_format", "structured_outputs"] } ] } ``` Цены в примере ответа условные. Одна модель — `GET https://veselo.ai/v1/models/deepseek/deepseek-v4.1-flash-ultrafast`: id со слешем пишется в путь как есть. ## Как выбрать модель - Нужен [вызов функций](https://veselo.ai/docs/tools) — бери модели, у которых в `supported_parameters` есть `tools`. - Нужен [ответ в JSON](https://veselo.ai/docs/structured-output) — `response_format`, а для ответа по схеме — `structured_outputs`. - Нужно читать [картинки](https://veselo.ai/docs/vision) — `image` в `input_modalities`. - Нужно [нарисовать картинку](https://veselo.ai/docs/images) — `type: "image"`; цена от — `pricing_rub.per_image`. - Нужно [видео](https://veselo.ai/docs/video) — `type: "video"`; [озвучка](https://veselo.ai/docs/speech) и [музыка](https://veselo.ai/docs/music) — `type: "audio"`, вид — в `audio.kind` (speech или music). - Длинные документы — смотри `context_length`: в него помещаются и вход, и ответ. - Модели с рассуждениями (`reasoning` в `supported_parameters`) думают перед ответом: отвечают дольше, а токены рассуждений оплачиваются как выход. ## Список меняется Каталог обновляется несколько раз в день: новые модели появляются, старые иногда уходят. Держи id модели в настройках программы, а не в разных местах кода. Если модели не стало, придёт 404 `model_not_found`; если она временно недоступна — 503 `model_unavailable` со списком замен в поле `alternatives`. ## Каких моделей нет Закрытых моделей OpenAI, Anthropic и Google — GPT, Claude и Gemini — нет: их создатели не работают с Россией. Запрос к ним вернёт 403 `model_not_allowed` или 404 `model_not_found`. Открытые модели этих компаний — `openai/gpt-oss-*` и `google/gemma-*` — есть: их запускают другие компании. --- # Чат: сообщения и параметры Chat Completions API в рублях: сообщения, системная роль, история диалога, параметры temperature, max_tokens и stop. Примеры на Python и JS. Основной метод — `POST https://veselo.ai/v1/chat/completions`. Ему передаются модель и список сообщений, в ответ приходит следующее сообщение — ответ модели. Формат — как у OpenAI Chat Completions. ## Сообщения | role | Что это | |---|---| | `system` | инструкция модели: роль, тон, формат ответа. Обычно первое сообщение | | `user` | сообщение человека или твоей программы | | `assistant` | прошлые ответы модели — для истории диалога | | `tool` | результат функции, которую вызвала модель, — см. [Вызов функций](https://veselo.ai/docs/tools) | `content` — строка, а для картинок во входе — массив частей, см. [Картинки во входе](https://veselo.ai/docs/vision). В одном запросе — до 2000 сообщений. curl: ```bash curl https://veselo.ai/v1/chat/completions \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek/deepseek-v4.1-flash-ultrafast", "temperature": 0.3, "max_tokens": 200, "messages": [ {"role": "system", "content": "Ты редактор. Отвечай коротко, по-русски, без вступлений."}, {"role": "user", "content": "Сократи до одного предложения: «Мы рады сообщить, что наш магазин теперь работает каждый день с девяти до девяти»."} ] }' ``` Python: ```python import os from openai import OpenAI client = OpenAI(base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"]) r = client.chat.completions.create( model="deepseek/deepseek-v4.1-flash-ultrafast", messages=[ {"role": "system", "content": "Ты редактор. Отвечай коротко, по-русски, без вступлений."}, {"role": "user", "content": "Сократи до одного предложения: «Мы рады сообщить, что наш магазин теперь работает каждый день с девяти до девяти»."}, ], temperature=0.3, max_tokens=200, ) print(r.choices[0].message.content) ``` JavaScript: ```js import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://veselo.ai/v1', apiKey: process.env.VESELO_API_KEY }); const r = await client.chat.completions.create({ model: 'deepseek/deepseek-v4.1-flash-ultrafast', messages: [ { role: 'system', content: 'Ты редактор. Отвечай коротко, по-русски, без вступлений.' }, { role: 'user', content: 'Сократи до одного предложения: «Мы рады сообщить, что наш магазин теперь работает каждый день с девяти до девяти».' }, ], temperature: 0.3, max_tokens: 200, }); console.log(r.choices[0].message.content); ``` ## Диалог API не помнит прошлые запросы. Чтобы модель продолжила разговор, присылай всю историю: прошлые вопросы (`user`) и ответы (`assistant`). Вся история каждый раз оплачивается как вход, поэтому в длинных диалогах старую часть стоит сокращать. Python: ```python import os from openai import OpenAI client = OpenAI(base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"]) history = [{"role": "system", "content": "Отвечай коротко."}] while True: q = input("> ") if not q: break history.append({"role": "user", "content": q}) r = client.chat.completions.create(model="deepseek/deepseek-v4.1-flash-ultrafast", messages=history, max_tokens=500) answer = r.choices[0].message.content history.append({"role": "assistant", "content": answer}) print(answer, f"({r.usage.cost_rub} ₽)") ``` JavaScript: ```js import OpenAI from 'openai'; import readline from 'node:readline'; const client = new OpenAI({ baseURL: 'https://veselo.ai/v1', apiKey: process.env.VESELO_API_KEY }); const history = [{ role: 'system', content: 'Отвечай коротко.' }]; process.stdout.write('> '); for await (const q of readline.createInterface({ input: process.stdin })) { if (!q) break; history.push({ role: 'user', content: q }); const r = await client.chat.completions.create({ model: 'deepseek/deepseek-v4.1-flash-ultrafast', messages: history, max_tokens: 500 }); const answer = r.choices[0].message.content; history.push({ role: 'assistant', content: answer }); console.log(answer, `(${r.usage.cost_rub} ₽)`); process.stdout.write('> '); } ``` ## Параметры | Параметр | Что делает | |---|---| | `max_tokens` | потолок длины ответа в токенах; от него зависит [удержание](https://veselo.ai/docs/pricing#hold). Можно писать и `max_completion_tokens` | | `temperature` | случайность: 0 — предсказуемо, ближе к 1 и выше — разнообразнее. Обычно от 0 до 2 | | `top_p` | другой способ ограничить случайность; обычно меняют что-то одно — его или `temperature` | | `stop` | строка или массив строк: встретив их, модель остановится | | `seed` | число для повторяемых ответов, если модель это поддерживает | | `frequency_penalty`, `presence_penalty` | штраф за повторы слов и тем | | `top_k`, `min_p`, `top_a`, `repetition_penalty` | тонкая настройка выборки у открытых моделей | | `reasoning_effort`, `reasoning` | сколько думать моделям с рассуждениями | | `tools`, `tool_choice`, `parallel_tool_calls` | [вызов функций](https://veselo.ai/docs/tools) | | `response_format` | [ответ в JSON](https://veselo.ai/docs/structured-output) | | `logprobs`, `top_logprobs`, `logit_bias` | вероятности токенов и их сдвиг | | `stream` | [ответ потоком](https://veselo.ai/docs/streaming) | | `provider` | какому [провайдеру](https://veselo.ai/docs/providers) отдать запрос: `order`, `only`, `ignore`, `allow_fallbacks`, `zdr`, `sort` | Какие параметры понимает модель — в её `supported_parameters` в [списке моделей](https://veselo.ai/docs/models). Параметр, которого модель не знает, она обычно пропускает. `n` — только 1: нужно несколько вариантов — сделай несколько запросов. Поля, которых нет в [справочнике](https://veselo.ai/docs/reference#chat), до модели не доходят и ошибки не вызывают: например, `user`, `metadata`, `store`, `stream_options`. ## Ответ | Поле | Что это | |---|---| | `choices[0].message.content` | текст ответа | | `choices[0].message.tool_calls` | вызовы функций, если модель их попросила | | `choices[0].finish_reason` | почему модель остановилась: `stop` — закончила, `length` — упёрлась в `max_tokens`, `tool_calls` — ждёт результат функции, `content_filter` — ответ остановлен фильтром | | `usage.prompt_tokens`, `usage.completion_tokens` | токены входа и выхода | | `usage.cost_rub` | цена запроса в рублях | | `provider` | кто ответил — [провайдер](https://veselo.ai/docs/providers) модели | | `id` | номер ответа: `chatcmpl-` и тот же `req_…`, что в заголовке `x-request-id` | Если `finish_reason` — `length`, ответ обрезан: подними `max_tokens` или попроси модель отвечать короче. Модели с рассуждениями могут вернуть ход мысли в поле `reasoning` сообщения. Эти токены входят в `completion_tokens` и оплачиваются как выход. --- # Стриминг: ответ по мере генерации Стриминг ответа нейросети по SSE в формате OpenAI: как включить, как читать поток, где цена запроса и что будет при обрыве. С `stream: true` ответ приходит кусками по мере того, как модель пишет, — как в чате: первые слова видны сразу, не нужно ждать весь ответ. Длинные ответы со стримингом надёжнее — соединение не простаивает. ## Формат Ответ — Server-Sent Events (`Content-Type: text/event-stream`), как у OpenAI: строки `data: {…}` с кусками `chat.completion.chunk`, между ними пустая строка. Новый текст — в `choices[0].delta.content`. - Последний кусок с данными несёт `usage` с ценой в рублях — `usage.cost_rub`. Его `choices` может быть пустым массивом: не обращайся к `choices[0]` без проверки. - Поток заканчивается строкой `data: [DONE]`. - Строки, которые начинаются с двоеточия (`: keep-alive`), служебные — пропускай их. - `stream_options` передавать не нужно: `usage` приходит всегда. - Заголовков `x-veselo-cost-rub` и `x-veselo-balance-rub` у потока нет: когда он начинается, цена ещё неизвестна. `x-request-id` и `x-ratelimit-*` есть. Поток: ```text : keep-alive data: {"id":"chatcmpl-req_5b2e…","object":"chat.completion.chunk","model":"deepseek/deepseek-v4.1-flash-ultrafast","choices":[{"index":0,"delta":{"role":"assistant","content":"Один"},"finish_reason":null}]} data: {"id":"chatcmpl-req_5b2e…","object":"chat.completion.chunk","model":"deepseek/deepseek-v4.1-flash-ultrafast","choices":[{"index":0,"delta":{"content":", два, три"},"finish_reason":null}]} data: {"id":"chatcmpl-req_5b2e…","object":"chat.completion.chunk","model":"deepseek/deepseek-v4.1-flash-ultrafast","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]} data: {"id":"chatcmpl-req_5b2e…","object":"chat.completion.chunk","model":"deepseek/deepseek-v4.1-flash-ultrafast","choices":[],"usage":{"prompt_tokens":16,"completion_tokens":9,"total_tokens":25,"cost_rub":0.01}} data: [DONE] ``` ## Примеры curl: ```bash curl -N https://veselo.ai/v1/chat/completions \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek/deepseek-v4.1-flash-ultrafast", "stream": true, "max_tokens": 500, "messages": [{"role": "user", "content": "Напиши короткое стихотворение про осень."}] }' ``` Python: ```python import os import openai from openai import OpenAI client = OpenAI(base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"]) stream = client.chat.completions.create( model="deepseek/deepseek-v4.1-flash-ultrafast", messages=[{"role": "user", "content": "Напиши короткое стихотворение про осень."}], max_tokens=500, stream=True, ) cost = None try: for chunk in stream: if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True) if chunk.usage: cost = chunk.usage.cost_rub except openai.APIError as e: # ошибка посреди потока print("\nПоток прервался:", e) if cost is not None: print(f"\nЦена: {cost} ₽") ``` JavaScript: ```js import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://veselo.ai/v1', apiKey: process.env.VESELO_API_KEY }); const stream = await client.chat.completions.create({ model: 'deepseek/deepseek-v4.1-flash-ultrafast', messages: [{ role: 'user', content: 'Напиши короткое стихотворение про осень.' }], max_tokens: 500, stream: true, }); let cost = null; try { for await (const chunk of stream) { const text = chunk.choices[0]?.delta?.content; if (text) process.stdout.write(text); if (chunk.usage) cost = chunk.usage.cost_rub; } } catch (e) { console.error('\nПоток прервался:', e.message); // ошибка посреди потока } if (cost !== null) console.log(`\nЦена: ${cost} ₽`); ``` JavaScript без SDK: ```js // Node 18+ или браузер: обычный fetch и разбор SSE const res = await fetch('https://veselo.ai/v1/chat/completions', { method: 'POST', headers: { Authorization: `Bearer ${process.env.VESELO_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'deepseek/deepseek-v4.1-flash-ultrafast', stream: true, max_tokens: 500, messages: [{ role: 'user', content: 'Напиши короткое стихотворение про осень.' }], }), }); if (!res.ok) { // ошибка до начала ответа — обычный JSON const { error } = await res.json().catch(() => ({ error: { code: `http_${res.status}`, message: res.statusText } })); throw new Error(`${res.status} ${error.code}: ${error.message}`); } const reader = res.body.getReader(); const decoder = new TextDecoder(); let buf = ''; let text = ''; let cost = null; for (;;) { const { value, done } = await reader.read(); if (done) break; buf += decoder.decode(value, { stream: true }); let nl; while ((nl = buf.indexOf('\n')) >= 0) { const line = buf.slice(0, nl).trim(); buf = buf.slice(nl + 1); if (!line.startsWith('data:')) continue; // пустые строки и «: keep-alive» const data = line.slice(5).trim(); if (data === '[DONE]') continue; const chunk = JSON.parse(data); if (chunk.error) throw new Error(`${chunk.error.code}: ${chunk.error.message}`); // ошибка посреди потока const piece = chunk.choices?.[0]?.delta?.content; if (piece) text += piece; if (chunk.usage) cost = chunk.usage.cost_rub; } } console.log(text); console.log('Цена:', cost, '₽'); ``` ## Ошибки в потоке - Ошибка до начала ответа — нет ключа, денег, модели — приходит обычным JSON с кодом HTTP, как без стриминга. - Ошибка посреди ответа приходит куском с полем `error` в том же формате, что [ошибки](https://veselo.ai/docs/errors), а за ним — `data: [DONE]`. SDK OpenAI в этом случае бросают исключение `APIError`. - Первый кусок ждём до 2 минут — дольше ответ придёт ошибкой 504 `upstream_timeout`. Если модель замолчала посреди ответа больше чем на 3 минуты, поток закрывается куском с ошибкой `upstream_timeout`. ## Обрыв и деньги Если программа закрыла соединение, запрос к модели прерывается, и списывается то, что модель успела сгенерировать: цена считается по длине запроса и полученного ответа. То же при обрыве со стороны модели. Цена такого запроса сразу видна в расходе — в `GET /v1/usage` и в кабинете. --- # Вызов функций (tools) Function calling через OpenAI-совместимый API: как описать функции, получить вызов от модели, вернуть результат и ответ. Примеры на Python и JS. Модель может попросить твою программу выполнить функцию — найти заказ, посчитать, сходить в базу — и ответить с учётом результата. Сама модель ничего не выполняет: она возвращает имя функции и аргументы, а вызывает функцию твоя программа. 1. Опиши функции в `tools`: имя, описание и параметры в JSON Schema. 2. Если модель решила вызвать функцию, в ответе будет `finish_reason: "tool_calls"` и список `message.tool_calls`. Аргументы — JSON-строка в `function.arguments`. 3. Выполни функции. Добавь в `messages` ответ модели с `tool_calls`, а за ним на каждый вызов сообщение `{"role": "tool", "tool_call_id": …, "content": …}` с результатом. 4. Отправь запрос ещё раз — модель ответит текстом или попросит новые вызовы. Python: ```python import json import os from openai import OpenAI client = OpenAI(base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"]) def get_weather(city): # здесь твой настоящий код: запрос в сервис погоды, в базу и т. п. return {"city": city, "temp_c": 7, "sky": "облачно"} FUNCTIONS = {"get_weather": get_weather} tools = [{ "type": "function", "function": { "name": "get_weather", "description": "Погода в городе сейчас", "parameters": { "type": "object", "properties": {"city": {"type": "string", "description": "Город, например Казань"}}, "required": ["city"], }, }, }] messages = [{"role": "user", "content": "Какая сейчас погода в Казани?"}] for _ in range(5): # не больше 5 кругов r = client.chat.completions.create(model="deepseek/deepseek-v4.1-flash-ultrafast", messages=messages, tools=tools, max_tokens=500) msg = r.choices[0].message if not msg.tool_calls: print(msg.content) break messages.append({ "role": "assistant", "content": msg.content or "", "tool_calls": [ {"id": c.id, "type": "function", "function": {"name": c.function.name, "arguments": c.function.arguments}} for c in msg.tool_calls ], }) for c in msg.tool_calls: args = json.loads(c.function.arguments or "{}") result = FUNCTIONS[c.function.name](**args) messages.append({"role": "tool", "tool_call_id": c.id, "content": json.dumps(result, ensure_ascii=False)}) ``` JavaScript: ```js import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://veselo.ai/v1', apiKey: process.env.VESELO_API_KEY }); // здесь твой настоящий код: запрос в сервис погоды, в базу и т. п. const functions = { get_weather: ({ city }) => ({ city, temp_c: 7, sky: 'облачно' }), }; const tools = [{ type: 'function', function: { name: 'get_weather', description: 'Погода в городе сейчас', parameters: { type: 'object', properties: { city: { type: 'string', description: 'Город, например Казань' } }, required: ['city'], }, }, }]; const messages = [{ role: 'user', content: 'Какая сейчас погода в Казани?' }]; for (let round = 0; round < 5; round++) { // не больше 5 кругов const r = await client.chat.completions.create({ model: 'deepseek/deepseek-v4.1-flash-ultrafast', messages, tools, max_tokens: 500 }); const msg = r.choices[0].message; if (!msg.tool_calls?.length) { console.log(msg.content); break; } messages.push({ role: 'assistant', content: msg.content ?? '', tool_calls: msg.tool_calls }); for (const call of msg.tool_calls) { const args = JSON.parse(call.function.arguments || '{}'); const result = functions[call.function.name](args); messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(result) }); } } ``` Ответ с вызовом: ```json { "id": "chatcmpl-req_0c4f6e2a9b1d4e8f8a7b6c5d4e3f2a1b", "object": "chat.completion", "model": "deepseek/deepseek-v4.1-flash-ultrafast", "choices": [ { "index": 0, "finish_reason": "tool_calls", "message": { "role": "assistant", "content": "", "tool_calls": [ { "id": "call_0_7c1d2e3f", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\": \"Казань\"}" } } ] } } ], "usage": { "prompt_tokens": 151, "completion_tokens": 19, "total_tokens": 170, "cost_rub": 0.01 } } ``` ## Параметры | Параметр | Что делает | |---|---| | `tools` | список функций: `{"type": "function", "function": {"name", "description", "parameters"}}` | | `tool_choice` | `auto` — модель решает сама (по умолчанию), `none` — без вызовов, `required` — вызвать обязательно, `{"type": "function", "function": {"name": "…"}}` — вызвать эту функцию | | `parallel_tool_calls` | `false` — не больше одного вызова за раз | ## Что важно - Функции понимают не все модели: нужно `tools` в `supported_parameters` модели. - Каждый круг — отдельный платный запрос, и описание функций каждый раз входит во вход. Описывай функции коротко. - Проверяй аргументы: модель может прислать неверный JSON или выдумать значение. - Ограничивай число кругов, чтобы программа не зациклилась. - Старые поля `functions` и `function_call` не поддерживаются — только `tools`. - В потоке вызовы приходят частями в `delta.tool_calls`: склеивай `function.arguments` по полю `index`. --- # Ответ в JSON (structured output) Как получить от нейросети ответ в JSON: response_format json_object и json_schema, проверка ответа и повтор. Примеры для DeepSeek. Когда ответ читает программа, а не человек, попроси модель отвечать в JSON. Есть два режима, оба задаются полем `response_format`. | Режим | Что даёт | Где работает | |---|---|---| | `{"type": "json_object"}` | ответ — корректный JSON; поля описываешь в тексте запроса | модели с `response_format` в `supported_parameters` | | `{"type": "json_schema", "json_schema": {…}}` | ответ по твоей JSON Schema: нужные поля и типы | модели со `structured_outputs` в `supported_parameters` | ## JSON-объект Напиши в сообщении слово JSON и перечисли поля: часть моделей без этого режим не включает. curl: ```bash curl https://veselo.ai/v1/chat/completions \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek/deepseek-v4.1-flash-ultrafast", "max_tokens": 200, "response_format": {"type": "json_object"}, "messages": [ {"role": "system", "content": "Извлеки имя, город и возраст. Ответь только JSON с полями name, city, age."}, {"role": "user", "content": "Меня зовут Аня, мне 27, живу в Перми."} ] }' ``` Python: ```python import json import os from openai import OpenAI client = OpenAI(base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"]) r = client.chat.completions.create( model="deepseek/deepseek-v4.1-flash-ultrafast", messages=[ {"role": "system", "content": "Извлеки имя, город и возраст. Ответь только JSON с полями name, city, age."}, {"role": "user", "content": "Меня зовут Аня, мне 27, живу в Перми."}, ], response_format={"type": "json_object"}, max_tokens=200, ) person = json.loads(r.choices[0].message.content) print(person["name"], person["city"], person["age"]) ``` Текст ответа: ```json {"name": "Аня", "city": "Пермь", "age": 27} ``` ## JSON по схеме Схема — обычная JSON Schema. С `"strict": true` модель держится схемы строже; для этого в `required` перечисли все поля и поставь `"additionalProperties": false`. Python: ```python import json import os from openai import OpenAI client = OpenAI(base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"]) schema = { "type": "object", "properties": { "name": {"type": "string"}, "city": {"type": "string"}, "age": {"type": "integer"}, }, "required": ["name", "city", "age"], "additionalProperties": False, } r = client.chat.completions.create( model="deepseek/deepseek-v4.1-flash-ultrafast", messages=[{"role": "user", "content": "Извлеки имя, город и возраст в JSON: «Меня зовут Аня, мне 27, живу в Перми»."}], response_format={"type": "json_schema", "json_schema": {"name": "person", "strict": True, "schema": schema}}, max_tokens=200, ) person = json.loads(r.choices[0].message.content) print(person) ``` JavaScript: ```js import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://veselo.ai/v1', apiKey: process.env.VESELO_API_KEY }); const r = await client.chat.completions.create({ model: 'deepseek/deepseek-v4.1-flash-ultrafast', max_tokens: 200, messages: [{ role: 'user', content: 'Извлеки имя, город и возраст в JSON: «Меня зовут Аня, мне 27, живу в Перми».' }], response_format: { type: 'json_schema', json_schema: { name: 'person', strict: true, schema: { type: 'object', properties: { name: { type: 'string' }, city: { type: 'string' }, age: { type: 'integer' } }, required: ['name', 'city', 'age'], additionalProperties: false, }, }, }, }); const person = JSON.parse(r.choices[0].message.content); console.log(person); ``` ## Проверяй ответ - Разбирай ответ через `json.loads` или `JSON.parse` и проверяй нужные поля. Не прошло — повтори запрос; можно добавить сообщение с текстом ошибки. - Модель, которая не поддерживает режим, может его пропустить: ответить обычным текстом или обернуть JSON в блок кода Markdown. Поэтому режим — дополнение к просьбе в тексте, а не замена. - Если `finish_reason` — `length`, JSON обрезан: подними `max_tokens`. --- # Провайдеры: кто отвечает на запрос Одну модель обслуживают разные провайдеры: у каждого своя цена и правила хранения запросов. Как выбрать провайдера и сколько это стоит. Каждую модель запускают на своих серверах одна или несколько компаний — провайдеры. Модель та же, а цена, скорость и правила хранения запросов у каждого свои. Провайдеры модели — в поле `providers` [списка моделей](https://veselo.ai/docs/models) и на странице модели на сайте. Каждый провайдер назван постоянным кодом: `id` вроде `p95bccf` и имя «Провайдер 95BCCF» — у провайдера они одни на всех моделях. ## Без выбора Если в запросе нет поля `provider`, запрос идёт по цене модели — `pricing_rub`. Он попадает к самому дешёвому провайдеру, а у моделей с `routing: "fastest"` — к самому быстрому из тех, что не дороже этой цены. Не ответил — к следующему такому же. Дороже цены модели запрос не обойдётся. ## Как выбрать провайдера Поле `provider` в теле `POST https://veselo.ai/v1/chat/completions` — объект с пожеланиями ниже. В нём — id провайдеров из `providers[].id`, регистр не важен. | Поле | Что делает | |---|---| | `order` | массив id: пробовать этих провайдеров первыми, в этом порядке | | `only` | массив id: только эти провайдеры | | `ignore` | массив id: все, кроме этих | | `allow_fallbacks` | `false` — не уходить к другим провайдерам, если выбранные не ответили. По умолчанию `true` | | `zdr` | `true` — только провайдеры, которые не хранят ни запрос, ни ответ (zero data retention). То же — `data_collection: "deny"` | | `sort` | `"price"` — сначала самые дешёвые из подходящих | curl: ```bash curl https://veselo.ai/v1/chat/completions \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek/deepseek-v4.1-flash-abliterated", "messages": [{"role": "user", "content": "Привет!"}], "provider": {"order": ["p21b172"], "allow_fallbacks": false} }' ``` Python: ```python from openai import OpenAI # pip install openai client = OpenAI(base_url="https://veselo.ai/v1", api_key="sk-vsl-ТВОЙ_КЛЮЧ") r = client.chat.completions.create( model="deepseek/deepseek-v4.1-flash-abliterated", messages=[{"role": "user", "content": "Привет!"}], # только провайдеры, которые не хранят запросы; сначала самые дешёвые из них extra_body={"provider": {"zdr": True, "sort": "price"}}, ) print(r.provider, r.usage.cost_rub) # кто ответил и цена в рублях ``` JavaScript: ```js import OpenAI from 'openai'; // npm i openai const client = new OpenAI({ baseURL: 'https://veselo.ai/v1', apiKey: process.env.VESELO_API_KEY }); const r = await client.chat.completions.create({ model: 'deepseek/deepseek-v4.1-flash-abliterated', messages: [{ role: 'user', content: 'Привет!' }], provider: { ignore: ['p1ba80e'] }, // всех, кроме одного }); console.log(r.provider, r.usage.cost_rub); ``` Коды в примерах — настоящие на момент написания; какие провайдеры у модели сейчас — смотри в `providers` или запросом ниже. ## Сколько стоит Выбрал провайдера сам — запрос стоит столько, сколько берёт тот, кто ответил: его цена — в `providers[].pricing_rub`. Провайдеры дороже цены модели помечены `default: false` — к ним запрос попадает, только если их выбрать. [Удержание](https://veselo.ai/docs/pricing#hold) считается по самому дорогому из подходящих провайдеров, списание — по факту. Кто ответил, видно в поле `provider` ответа, цена — в `usage.cost_rub`. ## Провайдеры модели Все провайдеры есть в `GET https://veselo.ai/v1/models` (поле `providers`). Одной модели — отдельным запросом, без ключа: curl: ```bash curl -s https://veselo.ai/v1/models/deepseek/deepseek-v4.1-flash-abliterated/endpoints ``` Ответ: ```json { "data": { "id": "deepseek/deepseek-v4.1-flash-abliterated", "name": "DeepSeek V4.1 Flash 1017 Abliterated", "routing": "cheapest", "endpoints": [ { "id": "p95bccf", "name": "Провайдер 95BCCF", "pricing_rub": { "input_per_1m": 13.41, "output_per_1m": 50.28, "cached_input_per_1m": 2.8 }, "context_length": 1048576, "max_output_tokens": 1000000, "input_modalities": ["text", "image"], "zdr": true, "quantization": "fp8", "default": true } ] } } ``` | Поле | Что это | |---|---| | `id` | код провайдера — что писать в `order`, `only` и `ignore` | | `name` | имя провайдера из его кода — так же он назван в поле `provider` ответа | | `pricing_rub` | цены в рублях за 1 млн токенов: вход, выход, вход из кэша | | `context_length`, `max_output_tokens` | у провайдера они бывают меньше, чем у модели | | `input_modalities` | что принимает: не все провайдеры читают картинки | | `zdr` | `true` — не хранит запросы и ответы | | `quantization` | точность весов на его серверах: `fp8`, `fp4` и т. п.; `null` — провайдер не сообщает | | `default` | `true` — не дороже цены модели: к нему может попасть запрос без `provider` | ## Ошибки Неизвестный id провайдера или условия, под которые не подходит ни один из них, — ошибка `invalid_request` с `param: "provider"` и списком провайдеров модели. Деньги не списываются. У модели без списка провайдеров поле `provider` не действует: запрос идёт как обычно. --- # Нейросети без цензуры по API Модели без цензуры по API за рубли: DeepSeek, GLM и Qwen без встроенных отказов (abliterated). Как подключить, цены и правила. Обычные модели обучены отказывать: «не могу с этим помочь». У моделей без цензуры этот механизм снят прямо с весов — такие версии называют abliterated. Знания и качество ответов те же, но модель не обрывает разговор отказом. Подходит для художественных текстов с мрачными и жёсткими сюжетами, исследований острых тем, проверки защит своих сервисов. ## Модели и цены Модели без цензуры — записи с uncensored: true в `GET https://veselo.ai/v1/models` (без ключа) или https://veselo.ai/models/bez-cenzury. В `GET /v1/models` у таких моделей поле `uncensored: true`. Вызываются так же, как остальные: `POST https://veselo.ai/v1/chat/completions`, стриминг, инструменты и формат ответа работают, если их умеет модель. Все модели без цензуры — на странице [моделей без цензуры](https://veselo.ai/models/bez-cenzury). ## Пример curl: ```bash curl https://veselo.ai/v1/chat/completions \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek/deepseek-v4.1-flash-abliterated", "messages": [{"role": "user", "content": "Напиши мрачную сцену для детектива: допрос в заброшенном складе"}] }' ``` Python: ```python import os from openai import OpenAI # pip install openai client = OpenAI(base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"]) r = client.chat.completions.create( model="deepseek/deepseek-v4.1-flash-abliterated", messages=[{"role": "user", "content": "Напиши мрачную сцену для детектива: допрос в заброшенном складе"}], ) print(r.choices[0].message.content) ``` ## Правила - Только для взрослых — с 18 лет. - Нельзя ничего, что запрещено законом: в том числе материалы с сексуальным насилием над детьми, призывы к насилию и экстремизму, мошенничество. - Нельзя порнографию и сексуальный контент, дипфейки и тексты, которые выдают за слова настоящего человека. - За то, как используются ответы, отвечает владелец ключа. Полные правила — в [условиях использования API](https://veselo.ai/legal/api), они действуют для всех моделей. --- # Картинки во входе Как отправить фото или скриншот нейросети по API: ссылкой или в base64, какие модели понимают изображения и как считается цена. Некоторые модели читают картинки: описывают фото, достают текст со скриншота, разбирают графики. Это модели, у которых в `input_modalities` есть `image`. У `deepseek/deepseek-v4.1-flash-ultrafast` картинок на входе нет, поэтому в примерах ниже — `z-ai/glm-4v-plus`. Python: ```python import requests # pip install requests models = requests.get("https://veselo.ai/v1/models", timeout=30).json()["data"] for m in models: if "image" in m["input_modalities"]: p = m["pricing_rub"] print(m["id"], p.get("input_per_1m"), p.get("output_per_1m")) ``` curl: ```bash curl -s https://veselo.ai/v1/models | jq -r '.data[] | select(.input_modalities | index("image")) | .id' ``` ## Как отправить картинку Картинка — часть сообщения `user`: вместо строки в `content` передаётся массив из текста и картинок. Картинка — объект `{"type": "image_url", "image_url": {"url": …}}`, где `url` — ссылка или сама картинка в base64. - **Ссылка** `https://…` должна открываться без входа и без защиты от роботов: картинку по ней скачивают при обработке запроса. - **base64** — `data:image/jpeg;base64,…` (или `image/png`, `image/webp`). Подходит для файлов с диска. Весь запрос — до 25 МБ, поэтому большие фото сначала уменьши. - В одном сообщении может быть несколько картинок. curl: ```bash curl https://veselo.ai/v1/chat/completions \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "z-ai/glm-4v-plus", "max_tokens": 300, "messages": [{ "role": "user", "content": [ {"type": "text", "text": "Что написано на картинке крупными буквами?"}, {"type": "image_url", "image_url": {"url": "https://veselo.ai/og.jpg"}} ] }] }' ``` Python: ```python import os from openai import OpenAI client = OpenAI(base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"]) r = client.chat.completions.create( model="z-ai/glm-4v-plus", max_tokens=300, messages=[{ "role": "user", "content": [ {"type": "text", "text": "Что написано на картинке крупными буквами?"}, {"type": "image_url", "image_url": {"url": "https://veselo.ai/og.jpg"}}, ], }], ) print(r.choices[0].message.content, r.usage.cost_rub) ``` JavaScript: ```js import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://veselo.ai/v1', apiKey: process.env.VESELO_API_KEY }); const r = await client.chat.completions.create({ model: 'z-ai/glm-4v-plus', max_tokens: 300, messages: [{ role: 'user', content: [ { type: 'text', text: 'Что написано на картинке крупными буквами?' }, { type: 'image_url', image_url: { url: 'https://veselo.ai/og.jpg' } }, ], }], }); console.log(r.choices[0].message.content, r.usage.cost_rub); ``` Своё фото с диска — в base64. Положи файл `photo.jpg` рядом со скриптом: Python: ```python import base64 import os from openai import OpenAI client = OpenAI(base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"]) with open("photo.jpg", "rb") as f: b64 = base64.b64encode(f.read()).decode() r = client.chat.completions.create( model="z-ai/glm-4v-plus", max_tokens=300, messages=[{ "role": "user", "content": [ {"type": "text", "text": "Опиши фото в двух предложениях."}, {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{b64}"}}, ], }], ) print(r.choices[0].message.content) ``` JavaScript: ```js import fs from 'node:fs'; import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://veselo.ai/v1', apiKey: process.env.VESELO_API_KEY }); const b64 = fs.readFileSync('photo.jpg').toString('base64'); const r = await client.chat.completions.create({ model: 'z-ai/glm-4v-plus', max_tokens: 300, messages: [{ role: 'user', content: [ { type: 'text', text: 'Опиши фото в двух предложениях.' }, { type: 'image_url', image_url: { url: `data:image/jpeg;base64,${b64}` } }, ], }], }); console.log(r.choices[0].message.content); ``` ## Цена Картинка оплачивается как токены входа: сколько токенов она стоит, решает модель, точное число придёт в `usage.prompt_tokens`. У некоторых моделей есть ещё цена за картинку — `per_image_input` в `pricing_rub`. В удержание каждая картинка идёт как 1500 токенов входа плюс эта цена. > Модель без `image` в `input_modalities` картинку не примет и вернёт ошибку. Ошибка не стоит денег. --- # Картинки по API за рубли Как нарисовать картинку по описанию через API: модели, пропорции, ссылки и base64. Примеры curl, Python и JavaScript, оплата в рублях. Отправь описание в `POST https://veselo.ai/v1/images/generations` — получишь готовую картинку в том же ответе. Здесь все нейросети Студии для картинок: Nano Banana, GPT Image, Qwen Image и Grok Imagine. Они рисуют одну картинку за запрос, а качество выбирается полем `quality` — от него зависит цена. Ответ ждёт картинку до 9 минут, обычно — секунды. Принимается только текст: правок по фото и стриминга пока нет. ## Модели и цены Актуальный список моделей с ценами в рублях: `GET https://veselo.ai/v1/models` (без ключа), выбери type: image или https://veselo.ai/models. В `GET /v1/models` выбирай записи с `type: "image"`. У нейросетей Студии цена картинки по качеству — `pricing_rub.per_image_quality` (`{"1K": …, "2K": …, "4K": …}`), а качества — `image.qualities`. В `pricing_rub.per_image` — самая низкая цена за одну картинку. Поле `image` показывает доступные `aspect_ratios`, `max_n` и `output_formats`. Пустой `output_formats` означает, что формат выбирает модель. Модели с оплатой выхода в токенах и векторные модели пока недоступны. ## Нарисовать картинку curl: ```bash curl https://veselo.ai/v1/images/generations \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen/qwen-image-2.0", "prompt": "Рыжий кот на подоконнике, акварель, мягкий утренний свет", "size": "1024x1024", "n": 1 }' ``` Python: ```python import os from openai import OpenAI # pip install openai client = OpenAI( base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"], timeout=600.0, max_retries=0, ) r = client.images.generate( model="qwen/qwen-image-2.0", prompt="Рыжий кот на подоконнике, акварель, мягкий утренний свет", size="1024x1024", n=1, response_format="url", ) for picture in r.data: print(picture.url) print("Цена:", r.model_dump()["usage"]["cost_rub"], "₽") ``` JavaScript: ```js const res = await fetch('https://veselo.ai/v1/images/generations', { method: 'POST', headers: { Authorization: `Bearer ${process.env.VESELO_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'qwen/qwen-image-2.0', prompt: 'Рыжий кот на подоконнике, акварель, мягкий утренний свет', aspect_ratio: '1:1', n: 1, }), signal: AbortSignal.timeout(600_000), }); const r = await res.json(); if (!res.ok) throw new Error(r.error.message); for (const picture of r.data) console.log(picture.url); console.log('Цена:', r.usage.cost_rub, '₽'); ``` Ответ: ```json { "created": 1794132000, "data": [{"url": "https://veselo.ai/media/api-images/2026-11-08/example.png"}], "usage": {"cost_rub": 5.68} } ``` Цена и ссылка в примере условные. Ссылки находятся в `data[].url`, цена всего запроса — в `usage.cost_rub` и заголовке `x-veselo-cost-rub`. Для поддержки сохрани `x-request-id`. ## Поля запроса | Поле | Что передать | |---|---| | `model` | обязательно: id модели с type: image | | `prompt` | обязательно: описание от 1 до 4000 знаков, не пустые пробелы | | `n` | целое число от 1 до image.max_n, не больше 4; по умолчанию 1. У нейросетей Студии — только 1. Модель может вернуть меньше | | `quality` | у нейросетей Студии: качество из image.qualities (1K, 2K, 4K, у Qwen — Стандарт/Pro…) или словами low, medium, high, auto. По умолчанию — как в Студии. От качества зависит цена | | `size` | ШИРИНАxВЫСОТА, например 1024x1024 или 1792x1024. Выбирает ближайшие пропорции модели, точные пиксели не гарантируются | | `aspect_ratio` | вместо size: значение из image.aspect_ratios. По умолчанию 1:1, если доступно, иначе первый вариант модели | | `response_format` | url по умолчанию или b64_json — base64 в data[].b64_json, без сохранения у нас | | `output_format` | png, jpeg или webp из image.output_formats; без поля формат выбирает модель | | `seed` | целое неотрицательное число до 9007199254740991, если seed есть в supported_parameters. Повтор результата не гарантируется | Передай либо `size`, либо `aspect_ratio`. Другие поля отвечают 400 с именем поля в `param`. Для `aspect_ratio` в Python SDK используй `extra_body={"aspect_ratio": "16:9"}` без `size`. ## Удержание и списание У нейросетей Студии API-счёт удерживает ровно цену картинки из `per_image_quality` и списывает её, когда картинка готова. Повтор с тем же `Idempotency-Key` и тем же телом вернёт ту же картинку без второго списания. Не дождались (504) или сервер обновлялся (503 — повтори через пару секунд) — денег не берём. У остальных моделей до генерации API-счёт удерживает цену `n` картинок с запасом ×1,5, а после — списывает цену каждой полученной картинки по прайсу. Размер на цену не влияет: цена — за картинку. Цена округляется вверх до копейки; остаток удержания освобождается. Ошибка ничего не стоит. Лимиты общие с текстом: 60 запросов в минуту и 10 одновременных на ключ. Без `Idempotency-Key` повтор генерации — новый платный запрос. Подробнее о счёте — [Цены и списания](https://veselo.ai/docs/pricing). ## Ссылки и base64 Картинки по ссылкам хранятся у нас 7 дней. Скачай результат к себе до истечения срока. С `response_format: "b64_json"` сервер возвращает base64 без префикса data: и не сохраняет файл. ## Если не получилось | HTTP / код | Что сделать | |---|---| | 400 / `invalid_request` | Проверь поле из param и возможности модели | | 401 / `missing_api_key`, `invalid_api_key` | Передай действующий ключ | | 402 / `insufficient_balance` | Пополни счёт или уменьши n | | 403 / `model_not_allowed`, `key_limit_reached`, `account_blocked` | Выбери доступную модель, проверь лимит ключа или обратись в поддержку | | 404 / `model_not_found` | Возьми id из GET /v1/models с type: image | | 422 / `content_refused` | Перепиши описание: проверка содержания его отклонила | | 429 / `rate_limited` | Подожди Retry-After секунд | | 502 / `upstream_error`; 503 / `model_unavailable`, `api_disabled`; 504 / `upstream_timeout` | Повтори позже или выбери другую модель | Все ошибки, включая 413 и 500, — в разделе [Ошибки](https://veselo.ai/docs/errors). Удержание при ошибке снимается без списания. --- # Видео по API: Seedance, Wan, Kling и MiniMax за рубли Как снять видео нейросетью по API: Seedance, Wan, Kling и MiniMax — задача, статус, ссылка на ролик. Оплата в рублях, возврат при сбое. Видео снимается дольше, чем отвечает чат: от пары минут до десяти. Поэтому это задача: отправляешь описание сцены — получаешь `id`, потом спрашиваешь статус, пока ролик не будет готов. Снимает та же очередь, что и Студия на сайте: если нейросеть не ответила, задача сама уходит к запасному поставщику. Актуальный список моделей с ценами в рублях: `GET https://veselo.ai/v1/models` (без ключа), выбери type: video или https://veselo.ai/models. У видеомоделей в `GET /v1/models` поле `type: "video"`. Цена за ролик — `pricing_rub.per_video["720p"]["10"]` (качество и длина в секундах), что можно выбрать — поле `video`: длины, качество, кадр, есть ли звук. ## Запустить ролик curl: ```bash curl https://veselo.ai/v1/videos \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: scene-001" \ -d '{ "model": "alibaba/wan-3.0", "prompt": "Кот в солнечных очках катается на скейте по набережной на закате", "duration": 5, "resolution": "480p", "aspect_ratio": "9:16" }' ``` Python: ```python import os, requests r = requests.post( "https://veselo.ai/v1/videos", headers={ "Authorization": f"Bearer {os.environ['VESELO_API_KEY']}", "Idempotency-Key": "scene-001", }, json={ "model": "alibaba/wan-3.0", "prompt": "Кот в солнечных очках катается на скейте по набережной на закате", "duration": 5, "resolution": "480p", "aspect_ratio": "9:16", }, timeout=120, ) r.raise_for_status() video = r.json() print(video["id"], video["price_rub"], "₽") ``` JavaScript: ```js const res = await fetch('https://veselo.ai/v1/videos', { method: 'POST', headers: { Authorization: `Bearer ${process.env.VESELO_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'scene-001', }, body: JSON.stringify({ model: 'alibaba/wan-3.0', prompt: 'Кот в солнечных очках катается на скейте по набережной на закате', duration: 5, resolution: '480p', aspect_ratio: '9:16', }), }); const video = await res.json(); console.log(video.id, video.price_rub, '₽'); ``` | Поле | Что это | |---|---| | `model` | обязательно: id видеомодели из `GET /v1/models`, например `alibaba/wan-3.0` | | `prompt` | обязательно: описание сцены, от 3 до 4000 знаков — кто в кадре, что делает, где, как движется камера | | `duration` | длина в секундах — из `video.durations` модели; по умолчанию самая короткая | | `resolution` | качество — из `video.resolutions`; по умолчанию самое дешёвое | | `aspect_ratio` | кадр — из `video.aspect_ratios`, по умолчанию `9:16` | | `audio` | со звуком, если модель умеет; по умолчанию `true` | Ответ — `202` с задачей: `id` вида `video_123`, `status`, `price_rub` — сколько списано, и выбранные `duration`, `resolution`, `aspect_ratio`. ## Узнать статус `GET https://veselo.ai/v1/videos/{id}` — тем же ключом или любым ключом того же аккаунта. Спрашивай раз в 10–15 секунд: чаще ролик готов не будет. Python: ```python import os, time, requests headers = {"Authorization": f"Bearer {os.environ['VESELO_API_KEY']}"} video_id = "video_123" # id из ответа на запуск while True: v = requests.get(f"https://veselo.ai/v1/videos/{video_id}", headers=headers, timeout=30).json() if v["status"] == "completed": print("Готово:", v["result"]["url"]) break if v["status"] == "failed": print("Не получилось:", v["error"]["message"], "— деньги вернули:", v["refunded"]) break print(v["status"], v["progress"], "%", v["stage"]) time.sleep(10) ``` JavaScript: ```js const headers = { Authorization: `Bearer ${process.env.VESELO_API_KEY}` }; const videoId = 'video_123'; // id из ответа на запуск for (;;) { const v = await (await fetch(`https://veselo.ai/v1/videos/${videoId}`, { headers })).json(); if (v.status === 'completed') { console.log('Готово:', v.result.url); break; } if (v.status === 'failed') { console.log('Не получилось:', v.error.message, 'возврат:', v.refunded); break; } console.log(v.status, v.progress, '%', v.stage); await new Promise((r) => setTimeout(r, 10_000)); } ``` | status | Что значит | |---|---| | `queued` | ждёт своей очереди | | `in_progress` | снимается: `progress` — проценты, `stage` — этап словами, `eta_seconds` — сколько примерно осталось | | `completed` | готово: `result.url` — MP4, `result.poster_url` — обложка | | `failed` | не получилось: `error.message` — почему, `refunded: true` — деньги вернулись на баланс | ## Деньги - Цена — за ролик целиком, как в Студии на сайте, и видна заранее в `GET /v1/models`. - Платит [API-счёт](https://veselo.ai/docs/pricing#wallet): при запуске цена удерживается, когда ролик готов — списывается. Не хватает — ошибка 402. - Не получилось — удержание снимается, деньги остаются на API-счёте, в ответе `refunded: true`. - Повтор запроса с тем же `Idempotency-Key` и тем же телом вернёт тот же ролик без второго списания. Тот же ключ с другим телом — 409 `idempotency_conflict`. Без заголовка каждый запрос — новый ролик. ## Готовый ролик Ссылка `result.url` открывается без ключа. Файлы хранятся ограниченное время — `result.expires_in_days` дней, поэтому скачай ролик к себе. Ролик появится и в «Моих видео» на сайте; уведомления в Telegram и на почту для роликов из API не приходят. ## Ограничения - Одновременно снимается до 3 роликов на аккаунт — вместе с роликами на сайте. Больше — 429 `rate_limited`. - Описание сцены проверяется так же, как в Студии. Не прошло — 422 `content_refused`, деньги не списаны. - Пока только текст: свои фото и видео к описанию через API не принимаются. --- # Озвучка текста по API: Gemini TTS и GPT-4o mini TTS за рубли Как озвучить текст голосом через API: модели, голоса, цена за текст до N знаков. В ответ — MP3, как у OpenAI audio.speech. Оплата в рублях. Отправь текст в `POST https://veselo.ai/v1/audio/speech` — в ответ придёт сам звук MP3, как у `audio.speech` в OpenAI. Текст читается как есть: без перевода и правок. Ответ ждёт озвучку до 9 минут, обычно — секунды. ## Модели, голоса и цены Актуальный список моделей с ценами в рублях: `GET https://veselo.ai/v1/models` (без ключа), выбери type: audio или https://veselo.ai/models. В `GET /v1/models` — записи с `type: "audio"` и `audio.kind: "speech"`. Голоса — `audio.voices` (id, имя и характер), сколько знаков за раз — `audio.max_chars`. Цена — за текст до стольких знаков: `pricing_rub.per_speech["2000"]` — сколько стоит текст до 2000 знаков. ## Озвучить текст curl: ```bash curl https://veselo.ai/v1/audio/speech \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "google/gemini-3.8-flash-tts", "voice": "Kore", "input": "Добрый вечер! Сегодня в программе — хорошие новости." }' \ --output speech.mp3 ``` Python: ```python import os from openai import OpenAI # pip install openai client = OpenAI(base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"], timeout=600.0, max_retries=0) with client.audio.speech.with_streaming_response.create( model="google/gemini-3.8-flash-tts", voice="Kore", input="Добрый вечер! Сегодня в программе — хорошие новости.", ) as r: print("Цена:", r.headers["x-veselo-cost-rub"], "₽") r.stream_to_file("speech.mp3") ``` JavaScript: ```js import fs from 'node:fs'; const res = await fetch('https://veselo.ai/v1/audio/speech', { method: 'POST', headers: { Authorization: `Bearer ${process.env.VESELO_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'openai/gpt-4o-mini-tts', voice: 'nova', input: 'Добрый вечер! Сегодня в программе — хорошие новости.', }), signal: AbortSignal.timeout(600_000), }); if (!res.ok) throw new Error((await res.json()).error.message); fs.writeFileSync('speech.mp3', Buffer.from(await res.arrayBuffer())); console.log('Цена:', res.headers.get('x-veselo-cost-rub'), '₽'); ``` ## Поля запроса | Поле | Что передать | |---|---| | `model` | обязательно: id модели с `audio.kind: "speech"` | | `input` | обязательно: текст от 1 знака до `audio.max_chars` — читается как есть | | `voice` | голос из `audio.voices` модели, без учёта регистра; по умолчанию — первый | | `response_format` | только `mp3` (по умолчанию) | | `speed` | только 1: скорость речи не меняется | Другие поля отвечают 400 с именем поля в `param`. Цена — в заголовке `x-veselo-cost-rub`, номер запроса для поддержки — `x-request-id`. ## Деньги - Цена — как в Студии на сайте и видна заранее в `GET /v1/models`: ступень по длине текста считает сервер. - Платит [API-счёт](https://veselo.ai/docs/pricing#wallet): цена удерживается до запуска и списывается, когда звук готов. Не хватает — 402. - Не получилось, не дождались (504) или сервер обновлялся (503 — повтори через пару секунд) — денег не берём. - Повтор с тем же `Idempotency-Key` и тем же телом вернёт ту же озвучку без второго списания. - Длинный текст — 400 с `param: "input"`: раздели его на части не длиннее `audio.max_chars`. --- # Музыка по API: Lyria за рубли Как сочинить музыку нейросетью через API: жанр, настроение, инструменты, слова песни — в ответ ссылка на MP3. Цена за трек в рублях. Отправь описание в `POST https://veselo.ai/v1/audio/music` — получишь ссылку на готовый трек MP3 в том же ответе. Опиши жанр, темп, настроение и инструменты; если нужна песня — добавь слова. Ответ ждёт трек до 9 минут. ## Модели и цены Актуальный список моделей с ценами в рублях: `GET https://veselo.ai/v1/models` (без ключа), выбери type: audio или https://veselo.ai/models. В `GET /v1/models` — записи с `audio.kind: "music"`. Цена за трек — `pricing_rub.per_track`, какой длины выходит трек — `audio.length`. ## Сочинить трек curl: ```bash curl https://veselo.ai/v1/audio/music \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "google/lyria-3.5", "prompt": "Спокойный лоу-фай бит с мягким пианино и шумом дождя, для учёбы" }' ``` Python: ```python import os, requests r = requests.post( "https://veselo.ai/v1/audio/music", headers={"Authorization": f"Bearer {os.environ['VESELO_API_KEY']}"}, json={"model": "google/lyria-3.5", "prompt": "Бодрый инди-рок с гитарами, 120 ударов в минуту"}, timeout=600, ) r.raise_for_status() track = r.json() print(track["data"][0]["url"], track["usage"]["cost_rub"], "₽") ``` Ответ: ```json { "created": 1794132000, "data": [{"url": "https://veselo.ai/media/r/example.mp3?e=1794736800&s=…"}], "usage": {"cost_rub": 19} } ``` | Поле | Что передать | |---|---| | `model` | обязательно: id модели с `audio.kind: "music"` | | `prompt` | обязательно: описание до 1500 знаков | | `response_format` | `url` по умолчанию или `b64_json` — MP3 в base64 в `data[].b64_json` | Ссылка живёт 7 дней — скачай трек к себе. Деньги — как у [озвучки](https://veselo.ai/docs/speech#money): цена удерживается до запуска и списывается, когда трек готов; ошибка ничего не стоит; повтор с тем же `Idempotency-Key` не списывает второй раз. --- # SDK, фреймворки и программы OpenAI-совместимый API в рублях: OpenAI SDK для Python и JS, LangChain, LlamaIndex, Vercel AI SDK, n8n, Make, Cursor, Continue и Cline. Везде, где можно подключить OpenAI, подойдёт и Весело: укажи адрес `https://veselo.ai/v1`, ключ `sk-vsl-…` и id модели из [списка](https://veselo.ai/docs/models). > Текст в формате OpenAI — только через Chat Completions (`/chat/completions`), Responses API (`/responses`) нет. Если библиотека зовёт его по умолчанию, переключи её на Chat Completions, иначе придёт 404 `not_found`. ## OpenAI SDK Официальные библиотеки OpenAI для Python и JavaScript. Адрес и ключ передаются в коде или через переменные окружения `OPENAI_BASE_URL` и `OPENAI_API_KEY`. Python: ```python import os from openai import OpenAI # pip install openai client = OpenAI(base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"]) r = client.chat.completions.create( model="deepseek/deepseek-v4.1-flash-ultrafast", messages=[{"role": "user", "content": "Объясни в двух предложениях, что такое API."}], max_tokens=300, ) print(r.choices[0].message.content) ``` JavaScript: ```js import OpenAI from 'openai'; // npm i openai const client = new OpenAI({ baseURL: 'https://veselo.ai/v1', apiKey: process.env.VESELO_API_KEY }); const r = await client.chat.completions.create({ model: 'deepseek/deepseek-v4.1-flash-ultrafast', messages: [{ role: 'user', content: 'Объясни в двух предложениях, что такое API.' }], max_tokens: 300, }); console.log(r.choices[0].message.content); ``` Переменные окружения: ```bash export OPENAI_BASE_URL="https://veselo.ai/v1" export OPENAI_API_KEY="$VESELO_API_KEY" # теперь OpenAI() без параметров ходит в Весело ``` ## LangChain Python: ```python import os from langchain_openai import ChatOpenAI # pip install langchain-openai llm = ChatOpenAI( model="deepseek/deepseek-v4.1-flash-ultrafast", base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"], max_tokens=300, ) print(llm.invoke("Объясни в двух предложениях, что такое API.").content) ``` JavaScript: ```js import { ChatOpenAI } from '@langchain/openai'; // npm i @langchain/openai const llm = new ChatOpenAI({ model: 'deepseek/deepseek-v4.1-flash-ultrafast', apiKey: process.env.VESELO_API_KEY, configuration: { baseURL: 'https://veselo.ai/v1' }, maxTokens: 300, }); const r = await llm.invoke('Объясни в двух предложениях, что такое API.'); console.log(r.content); ``` ## LlamaIndex Через `OpenAILike`: обычный класс `OpenAI` из LlamaIndex знает только модели OpenAI. Python: ```python import os from llama_index.llms.openai_like import OpenAILike # pip install llama-index-llms-openai-like llm = OpenAILike( model="deepseek/deepseek-v4.1-flash-ultrafast", api_base="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"], is_chat_model=True, is_function_calling_model=True, context_window=1048576, # context_length модели из GET /v1/models max_tokens=300, ) print(llm.complete("Объясни в двух предложениях, что такое API.")) ``` ## Vercel AI SDK Через провайдер `@ai-sdk/openai-compatible`: провайдер `@ai-sdk/openai` в новых версиях по умолчанию зовёт Responses API. JavaScript: ```js import { createOpenAICompatible } from '@ai-sdk/openai-compatible'; // npm i ai @ai-sdk/openai-compatible import { generateText } from 'ai'; const veselo = createOpenAICompatible({ name: 'veselo', baseURL: 'https://veselo.ai/v1', apiKey: process.env.VESELO_API_KEY, }); const { text } = await generateText({ model: veselo('deepseek/deepseek-v4.1-flash-ultrafast'), prompt: 'Объясни в двух предложениях, что такое API.', }); console.log(text); ``` ## n8n 1. Добавь узел **HTTP Request**: метод `POST`, адрес `https://veselo.ai/v1/chat/completions`. 2. Authentication — **Generic Credential Type** → **Header Auth**: имя `Authorization`, значение `Bearer sk-vsl-…`. 3. Включи **Send Body**, тип **JSON**, и вставь тело запроса — пример ниже. 4. Ответ модели — в выражении `{{ $json.choices[0].message.content }}`. Тело запроса: ```json { "model": "deepseek/deepseek-v4.1-flash-ultrafast", "max_tokens": 500, "messages": [ { "role": "system", "content": "Отвечай коротко." }, { "role": "user", "content": "Придумай заголовок для поста о скидках на зимние шины." } ] } ``` Текст из прошлого узла подставляй выражением без кавычек вокруг: `"content": {{ JSON.stringify($json.text) }}` — так кавычки и переносы строк в тексте не сломают JSON. ## Make 1. Добавь модуль **HTTP → Make a request**. 2. URL — `https://veselo.ai/v1/chat/completions`, метод — `POST`. 3. В Headers добавь `Authorization` со значением `Bearer sk-vsl-…`. 4. Body type — **Raw**, Content type — **JSON (application/json)**, в Request content — тело запроса, как для n8n выше. 5. Включи **Parse response**. Ответ модели — в `choices` → `message` → `content`. ## Cursor Settings → Models: в поле **OpenAI API Key** вставь ключ `sk-vsl-…`, включи **Override OpenAI Base URL** и укажи `https://veselo.ai/v1`, затем добавь модель `deepseek/deepseek-v4.1-flash-ultrafast`. Свой ключ работает в чате; автодополнение Tab идёт через модели Cursor. Чтобы Cursor сам смотрел модели, баланс и спрашивал другие модели, подключи [MCP-сервер](https://veselo.ai/docs/mcp#cursor). ## Continue В `config.yaml` добавь модель с провайдером `openai` и нашим адресом: config.yaml: ```text name: My config version: 0.0.1 schema: v1 models: - name: DeepSeek (Весело) provider: openai model: deepseek/deepseek-v4.1-flash-ultrafast apiBase: https://veselo.ai/v1 apiKey: sk-vsl-… ``` ## Cline Настройки → **API Provider: OpenAI Compatible**. Base URL — `https://veselo.ai/v1`, API Key — `sk-vsl-…`, Model ID — `deepseek/deepseek-v4.1-flash-ultrafast`. ## Другие программы Подойдёт любая программа с настройкой «OpenAI-compatible», «Custom OpenAI» или «свой адрес OpenAI»: адрес — `https://veselo.ai/v1`, ключ — `sk-vsl-…`, модель — id из [списка](https://veselo.ai/docs/models). Если программа сама дописывает `/v1` к адресу, укажи адрес без `/v1` на конце. Программы и библиотеки в формате Anthropic — Claude Code, SDK Anthropic — подключаются к своему входу `/v1/messages`: [Claude Code и формат Anthropic](https://veselo.ai/docs/anthropic). --- # Claude Code и формат Anthropic Claude Code и SDK Anthropic на открытых моделях за рубли: адрес https://veselo.ai, ключ sk-vsl-… и метод POST /v1/messages в формате Anthropic Messages. Программы, которые говорят с нейросетью в формате Anthropic Messages, — Claude Code, SDK Anthropic для Python и JavaScript и другие — работают с Весело без доработок. Им нужны адрес `https://veselo.ai`, ключ `sk-vsl-…` и id текстовой модели из [списка](https://veselo.ai/docs/models). Метод — `POST https://veselo.ai/v1/messages`. > Моделей Claude у нас нет: Anthropic не работает с Россией. Формат тот же, а отвечают открытые модели из [каталога](https://veselo.ai/models) — например `deepseek/deepseek-v4.1-flash-ultrafast`. Запрос с моделью `claude-…` вернёт 404 `model_not_found`. ## Claude Code 1. Выпусти в [кабинете](https://veselo.ai/developer) отдельный ключ для Claude Code и поставь ему месячный лимит: каждый шаг Claude Code — платный запрос. 2. Пополни [API-счёт](https://veselo.ai/developer/wallet). 3. Задай переменные окружения, как в примере ниже, и запусти `claude` в том же терминале. Или впиши их в блок `env` файла `~/.claude/settings.json` — тогда они действуют всегда. Терминал: ```bash export ANTHROPIC_BASE_URL="https://veselo.ai" export ANTHROPIC_AUTH_TOKEN="$VESELO_API_KEY" export ANTHROPIC_API_KEY="" export ANTHROPIC_MODEL="deepseek/deepseek-v4.1-flash-ultrafast" export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek/deepseek-v4.1-flash-ultrafast" export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek/deepseek-v4.1-flash-ultrafast" export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek/deepseek-v4.1-flash-ultrafast" export CLAUDE_CODE_SUBAGENT_MODEL="deepseek/deepseek-v4.1-flash-ultrafast" export CLAUDE_CODE_MAX_CONTEXT_TOKENS="1048576" claude ``` settings.json: ```json { "env": { "ANTHROPIC_BASE_URL": "https://veselo.ai", "ANTHROPIC_AUTH_TOKEN": "sk-vsl-…", "ANTHROPIC_API_KEY": "", "ANTHROPIC_MODEL": "deepseek/deepseek-v4.1-flash-ultrafast", "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek/deepseek-v4.1-flash-ultrafast", "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek/deepseek-v4.1-flash-ultrafast", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek/deepseek-v4.1-flash-ultrafast", "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek/deepseek-v4.1-flash-ultrafast", "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "1048576" } } ``` - `ANTHROPIC_BASE_URL` — без `/v1` на конце: Claude Code сам допишет `/v1/messages`. - `ANTHROPIC_AUTH_TOKEN` — ключ `sk-vsl-…`, Claude Code передаёт его в заголовке `Authorization: Bearer`. Пустой `ANTHROPIC_API_KEY` нужен, чтобы вместо нашего ключа не ушёл другой — например, ключ Anthropic из твоих переменных окружения. - Модели — во всех пяти переменных: Claude Code зовёт и «быструю» модель для фоновых задач, и модели помощников. Если какую-то не задать, её запросы уйдут к модели Claude и получат 404 `model_not_found`. - Модели можно взять разные: посильнее — в `ANTHROPIC_MODEL`, подешевле — в `ANTHROPIC_DEFAULT_HAIKU_MODEL`. Цены — в [каталоге](https://veselo.ai/models). - `CLAUDE_CODE_MAX_CONTEXT_TOKENS` — сколько токенов модель помнит. Наших моделей Claude Code не знает: он предупредит об этом и будет считать, что их контекст — 200 000 токенов. У DeepSeek V4.1 Flash Ultrafast — 1 048 576. С верным числом Claude Code вовремя сожмёт разговор, а иначе длинная сессия упрётся в ошибку 400. У других моделей число своё. > Claude Code просит ответ до 32 000 токенов, и на время каждого шага удерживается цена такого ответа. Если модель отвечает 400 из-за длины ответа или хочется удерживать меньше, задай `CLAUDE_CODE_MAX_OUTPUT_TOKENS`, например `8192`. Если потолок ответа модели известен (`max_output_tokens` в `GET https://veselo.ai/v1/models`), сервер сам уменьшает до него слишком большой `max_tokens`. Цену в `/cost` Claude Code считает сам, по ценам моделей Claude, — с нашей она не совпадает. Сколько стоил запрос на самом деле — `usage.cost_rub` и расход в [кабинете](https://veselo.ai/developer). **Что не работает.** Поиск в интернете (WebSearch) Claude Code делает инструментом сервера Anthropic — у нас таких инструментов нет, запрос с ним получит 400 `invalid_request`. PDF модели не получают: вместо документа в разговор встаёт пометка, что его нет; текст и картинки проходят. Подсчёта токенов (`/v1/messages/count_tokens`) нет — ответ 404. MCP-сервер Весело — другое: Claude Code остаётся на своей модели и через MCP сам снимает видео, рисует картинки и спрашивает наши модели. Как подключить — [MCP-сервер](https://veselo.ai/docs/mcp#claude-code). ## Запрос `POST https://veselo.ai/v1/messages`. Ключ — в `x-api-key: sk-vsl-…`, как у SDK Anthropic, или в `Authorization: Bearer sk-vsl-…`. Заголовок `anthropic-version` принимаем любой, но он не обязателен; `anthropic-beta` не учитываем. | Поле | Что с ним делаем | |---|---| | `model` | обязательно: id текстовой модели из `GET /v1/models` | | `max_tokens` | обязательно: потолок длины ответа, от него зависит удержание; больше `max_output_tokens` модели — уменьшаем до него | | `messages` | роли `user`, `assistant` и `system`; `content` — строка или блоки `text`, `image` (base64 или url), `document` с текстом, `tool_use`, `tool_result`, `thinking` | | `system` | строка или блоки `text` | | `stream` | ответ потоком SSE в формате Anthropic | | `temperature`, `top_p`, `top_k` | передаём модели | | `stop_sequences` | на чём остановиться | | `tools` | свои инструменты с `input_schema`; инструменты сервера Anthropic (`web_search`, `code_execution` и другие) — 400 | | `tool_choice` | `auto`, `any`, `tool`, `none` и `disable_parallel_tool_use` | | `thinking` | `enabled` или `adaptive`: рассуждения модели, если она их пишет, приходят блоками `thinking`. Длину рассуждений поле не задаёт — модели думают по-своему | | `provider` | наше поле — выбор провайдера модели, как в разделе [Провайдеры](https://veselo.ai/docs/providers) | Прочие поля — `metadata`, `cache_control`, `service_tier` и другие — принимаем, но нейросети не передаём. Блоки `thinking` из прошлых ответов тоже не передаём: нашим моделям их не прочитать. Вместо PDF и других файлов в `document` модель видит пометку. `mcp_servers` — 400: MCP-серверы из запроса мы не подключаем. Сообщения `system` в середине разговора (так делает Claude Code) многие модели не принимают, поэтому они доходят до модели текстом в сообщении `user`, в тегах ``. Сообщения одной роли подряд склеиваем в одно — так делает и Anthropic. ## Ответ Сообщение Anthropic: `id` вида `msg_req_…`, в `content` — блоки `text`, `tool_use` и, если включён `thinking`, `thinking`. `stop_reason` — `end_turn`, `max_tokens`, `tool_use` или `refusal` (отказ фильтра); `stop_sequence` — если модель сообщила, на какой строке из `stop_sequences` остановилась. В `usage` — `input_tokens` (без входа из кэша), `cache_read_input_tokens`, `output_tokens` и цена в рублях `cost_rub`; без потока та же цена — в заголовке `x-veselo-cost-rub`. curl: ```bash curl https://veselo.ai/v1/messages \ -H "x-api-key: $VESELO_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "deepseek/deepseek-v4.1-flash-ultrafast", "max_tokens": 300, "messages": [{"role": "user", "content": "Объясни в двух предложениях, что такое API."}] }' ``` Python: ```python import os import anthropic # pip install anthropic client = anthropic.Anthropic(base_url="https://veselo.ai", api_key=os.environ["VESELO_API_KEY"]) msg = client.messages.create( model="deepseek/deepseek-v4.1-flash-ultrafast", max_tokens=300, messages=[{"role": "user", "content": "Объясни в двух предложениях, что такое API."}], ) print("".join(b.text for b in msg.content if b.type == "text")) ``` JavaScript: ```js import Anthropic from '@anthropic-ai/sdk'; // npm i @anthropic-ai/sdk const client = new Anthropic({ baseURL: 'https://veselo.ai', apiKey: process.env.VESELO_API_KEY }); const msg = await client.messages.create({ model: 'deepseek/deepseek-v4.1-flash-ultrafast', max_tokens: 300, messages: [{ role: 'user', content: 'Объясни в двух предложениях, что такое API.' }], }); console.log(msg.content.filter((b) => b.type === 'text').map((b) => b.text).join('')); ``` Ответ: ```json { "id": "msg_req_6f1c…", "type": "message", "role": "assistant", "model": "deepseek/deepseek-v4.1-flash-ultrafast", "content": [{ "type": "text", "text": "API — это способ, которым одна программа просит другую что-то сделать…" }], "stop_reason": "end_turn", "stop_sequence": null, "usage": { "input_tokens": 18, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "output_tokens": 64, "cost_rub": 0.01 } } ``` SDK Anthropic сами дописывают `/v1/messages` к адресу, поэтому в `base_url` — `https://veselo.ai` без `/v1`. ## Поток С `stream: true` ответ идёт событиями Anthropic: `message_start`; затем блоки — `content_block_start`, `content_block_delta` (`text_delta`, `thinking_delta`, `input_json_delta`) и `content_block_stop`; потом `message_delta` с `stop_reason` и `usage` и в конце `message_stop`. Цена в рублях — `usage.cost_rub` в `message_delta`. Если долго нет новых событий — например, модель думает молча, — приходят события `ping`. Аргументы инструмента приходят одним куском `input_json_delta`, когда модель дописала вызов. Ошибка посреди потока — событие `error`, после него событий нет. Оборванный поток стоит столько, сколько модель успела написать, — как у [стриминга](https://veselo.ai/docs/streaming) в формате OpenAI. Python: ```python with client.messages.stream( model="deepseek/deepseek-v4.1-flash-ultrafast", max_tokens=1000, messages=[{"role": "user", "content": "Напиши короткое стихотворение о Москве."}], ) as stream: for text in stream.text_stream: print(text, end="", flush=True) ``` События: ```text event: message_start data: {"type":"message_start","message":{"id":"msg_req_6f1c…","type":"message","role":"assistant","model":"deepseek/deepseek-v4.1-flash-ultrafast","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":0,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":0}}} event: content_block_start data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}} event: content_block_delta data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Москва"}} event: content_block_stop data: {"type":"content_block_stop","index":0} event: message_delta data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":21,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":48,"cost_rub":0.01}} event: message_stop data: {"type":"message_stop"} ``` В `message_start` токенов ещё нет — настоящие числа приходят в `message_delta`, когда модель закончила. ## Ошибки Ошибки `/v1/messages` — в формате Anthropic, SDK Anthropic понимают их без доработок. Коды и тексты — те же, что в разделе [Ошибки](https://veselo.ai/docs/errors): постоянный `code` лежит внутри `error`, рядом — `param` и поля вроде `required_rub`. Тип — как у Anthropic: 402 — `billing_error`, 413 — `request_too_large`, 503 `model_unavailable` — `overloaded_error`, 504 — `timeout_error`. Ответ 402: ```json { "type": "error", "error": { "type": "billing_error", "message": "Не хватает денег на балансе для этого запроса.", "code": "insufficient_balance", "required_rub": 1.37, "available_rub": 0, "topup_url": "https://veselo.ai/developer/wallet" }, "request_id": "req_6f1c…" } ``` Деньги и лимиты — как у `/chat/completions`: удержание по `max_tokens`, списание по факту, ошибка нейросети не стоит денег; 60 запросов в минуту и 10 одновременных на ключ. Подробнее — [Цены и списания](https://veselo.ai/docs/pricing) и [Лимиты](https://veselo.ai/docs/limits). --- # Как передать ключ своей нейросети Как подключить API Весело к ИИ-агенту или помощнику в коде: готовый текст для нейросети, вся документация в llms.txt, отдельный ключ с лимитом. > Если помощнику нужно самому снимать видео, рисовать и спрашивать модели — ключ не нужен: подключи [MCP-сервер без ключа](https://veselo.ai/docs/mcp#no-key), вход — кнопкой «Разрешить» на veselo.ai. Ключ нужен, когда помощник пишет программу, которая будет звать API сама. ИИ-агенты и помощники в коде — Claude Code, Cursor, Codex, Cline — могут сами написать программу, которая зовёт API. Им нужны три вещи: адрес, ключ и документация. 1. Выпусти для агента отдельный ключ в [кабинете](https://veselo.ai/developer) и поставь ему месячный лимит, например 300 ₽. Агент может ошибиться и зациклить запросы — лимит ограничит траты. 2. Положи ключ в переменную окружения `VESELO_API_KEY` там, где агент запускает код. В сам чат ключ не вставляй. 3. Дай агенту текст ниже: в нём адрес, правила и ссылка на документацию. Текст для нейросети: ```text Подключи API Весело — нейросети по API за рубли в формате OpenAI Chat Completions. Адрес: https://veselo.ai/v1 (POST /chat/completions, GET /models, GET /balance, GET /usage). Ключ лежит в переменной окружения VESELO_API_KEY. Передавай его в заголовке Authorization: Bearer. Не печатай ключ и не сохраняй его в файлах проекта. Вся документация одним файлом: https://veselo.ai/docs/llms.txt — прочитай её перед работой. Модель по умолчанию — deepseek/deepseek-v4.1-flash-ultrafast, другие — GET https://veselo.ai/v1/models. Каждый запрос платный: ставь max_tokens, цену бери из usage.cost_rub, остаток — GET https://veselo.ai/v1/balance. Ошибки 429 и 5xx повторяй с паузой (заголовок Retry-After), остальные 4xx не повторяй. ``` ## Документация для ИИ Вся документация одним текстом в Markdown — [veselo.ai/docs/llms.txt](https://veselo.ai/docs/llms.txt). Отдай ссылку агенту или скачай файл и приложи к запросу. У каждого раздела на сайте есть кнопка «Скопировать для ИИ» — раздел целиком в Markdown. Описание методов в формате OpenAPI 3.1 — `GET https://veselo.ai/v1/openapi.json`, без ключа: его понимают генераторы клиентов и Postman. ## Нейросеть сама зовёт модели Если нужно, чтобы помощник сам спрашивал другие модели, смотрел цены и баланс, подключи [MCP-сервер](https://veselo.ai/docs/mcp) — код писать не нужно. ## Шпаргалка для агента - Формат — OpenAI Chat Completions: SDK OpenAI работают с `base_url` `https://veselo.ai/v1`. Responses API, эмбеддингов и Batch API нет. - Формат Anthropic Messages — `POST /messages`: SDK Anthropic работают с `base_url` `https://veselo.ai`, без `/v1`. Моделей Claude нет — модели те же, что у чата: текстовые из `GET /models`. - Ключ — `Authorization: Bearer sk-vsl-…`. Без ключа работают только `GET /models` и `GET /openapi.json`. - id модели — вида `vendor/model`, только из `GET /models`. - `n` — только 1. Поля, которых нет в [справочнике](https://veselo.ai/docs/reference#chat), отбрасываются. - Удержание — по `max_tokens`, без него — до 16 384 токенов ответа. Ставь `max_tokens`. - Цена — `usage.cost_rub` (в потоке — в последнем куске) и заголовок `x-veselo-cost-rub`. - Ошибки — `{"error": {"message", "type", "code", "param", "request_id"}}`. 402 — не хватает денег (`required_rub`, `available_rub`), 429 — подожди `Retry-After` секунд. - Лимиты — 60 запросов в минуту и 10 одновременных на ключ, тело — до 25 МБ. - Стриминг — SSE; конец — `data: [DONE]`; ошибка посреди потока — кусок с `error`. - Без стриминга ставь тайм-аут клиента не меньше 5 минут: запрос дорабатывает и оплачивается, даже если клиент отключился. --- # MCP-сервер MCP-сервер Весело для Claude, ChatGPT, Claude Code, Cursor, VS Code и Codex без ключа: вход на veselo.ai и кнопка «Разрешить». Видео, картинки, цены, баланс. MCP — способ дать ИИ-помощнику инструменты. Через наш MCP-сервер помощник сам снимает видео, рисует картинки, смотрит модели и цены, задаёт вопросы другим моделям, проверяет баланс и расход. Деньги, лимиты и ошибки — те же, что у API. ## Подключить без ключа 1. Добавь в свою нейросеть адрес `https://veselo.ai/mcp` — как именно, написано ниже для [Claude](https://veselo.ai/docs/mcp#claude), [Claude Code](https://veselo.ai/docs/mcp#claude-code), [Cursor](https://veselo.ai/docs/mcp#cursor), [VS Code](https://veselo.ai/docs/mcp#vscode), [ChatGPT](https://veselo.ai/docs/mcp#chatgpt) и [Codex](https://veselo.ai/docs/mcp#codex-oauth). 2. Нейросеть откроет veselo.ai. Войди как обычно: Telegram, Яндекс ID, VK ID или почта. 3. Нажми «Разрешить». Можно сразу поставить лимит расхода в месяц — или оставить без лимита. 4. Готово: ключ выпускать и копировать не нужно. Платные инструменты — видео, картинки и ответы моделей — тратят API-счёт: пополни его от 100 ₽ в [кабинете](https://veselo.ai/developer/wallet), нейросеть сама подскажет, когда пора. > Кнопки «Добавить в Claude», «Добавить в Cursor», «Добавить в VS Code» и шаги для ChatGPT и Codex — на странице [Подключить к нейросети](https://veselo.ai/connect). Подключённые нейросети видны в [кабинете API](https://veselo.ai/developer): там можно поменять лимит или нажать «Отключить» — доступ пропадёт сразу. | Что | Значение | |---|---| | Адрес | `https://veselo.ai/mcp` | | Протокол | Streamable HTTP, JSON-RPC 2.0, без сессий | | Вход | без ключа — кнопкой «Разрешить» на veselo.ai (OAuth 2.1, см. [для разработчиков клиентов](https://veselo.ai/docs/mcp#oauth)); или ключ: заголовок `Authorization: Bearer sk-vsl-…` | ## Инструменты | Инструмент | Аргументы | Что делает | |---|---|---| | `list_models` | `type`, `query`, `limit` — все необязательные | модели с ценами в рублях; `type` — text (по умолчанию), image, video или audio (озвучка и музыка); `query` — поиск по id и названию, `limit` — сколько показать, по умолчанию 30 | | `get_model` | `id` | одна модель подробно: контекст, что принимает на вход, цены | | `chat` | `model`; `prompt` или `messages`; `system`, `max_tokens`, `temperature` | спросить модель: возвращает текст ответа и цену. Платно | | `get_balance` | — | сколько денег доступно — как `GET /v1/balance` | | `get_usage` | `days` | расход по дням и моделям — как `GET /v1/usage` | | `generate_image` | `model`, `prompt`; `aspect_ratio`, `quality`, `n` | нарисовать картинки: ссылки и цена в рублях, плюс structuredContent с тем же ответом. Платно, как POST /v1/images/generations | | `generate_speech` | `model`, `input`; `voice` | озвучить текст: ссылка на MP3 и цена в рублях. Платно, как `POST /v1/audio/speech` | | `generate_music` | `model`, `prompt` | сочинить трек: ссылка на MP3 и цена в рублях. Платно, как `POST /v1/audio/music` | | `generate_video` | `model`, `prompt`; `duration`, `resolution`, `aspect_ratio`, `audio` | запустить видео: возвращает `id` и цену. Платно, как `POST /v1/videos` | | `get_video` | `id` | статус видео и ссылка на готовый ролик — как `GET /v1/videos/{id}` | Каждый вызов `chat`, `generate_image`, `generate_speech` или `generate_music` списывает деньги с API-счёта, как обычный запрос, а `generate_video` — цену ролика, как [видео по API](https://veselo.ai/docs/video). Ошибка инструмента приходит текстом с кодом из [таблицы ошибок](https://veselo.ai/docs/errors) в скобках, например `(insufficient_balance)`: помощник видит причину. > Сколько раз звать платные инструменты, помощник решает сам — поставь лимит в месяц: на экране «Разрешить» или потом в кабинете API (а для ключа — отдельный ключ с лимитом). ## Claude — сайт и приложение Настройки → «Коннекторы» (Settings → Connectors) → «Добавить свой коннектор» (Add custom connector). Название — Весело, адрес — `https://veselo.ai/mcp`, остальные поля не нужны. Нажми «Подключить» (Connect): откроется veselo.ai — войди и нажми «Разрешить». Коннектор работает и на сайте claude.ai, и в приложениях Claude на компьютере и телефоне. ## Claude Code Терминал: ```bash claude mcp add --transport http veselo https://veselo.ai/mcp ``` Потом в Claude Code набери `/mcp`, выбери veselo и «Authenticate» — или выполни в терминале `claude mcp login veselo`. Откроется veselo.ai: войди и нажми «Разрешить». Claude Code сам обновляет вход, повторять не нужно. ## Cursor Файл `~/.cursor/mcp.json` — для всех проектов, или `.cursor/mcp.json` — в проекте. После сохранения в настройках MCP у сервера появится кнопка входа: она откроет veselo.ai. mcp.json: ```json { "mcpServers": { "veselo": { "url": "https://veselo.ai/mcp" } } } ``` ## VS Code Файл `.vscode/mcp.json` в проекте. При первом запуске сервера VS Code попросит войти — откроется veselo.ai. .vscode/mcp.json: ```json { "servers": { "veselo": { "type": "http", "url": "https://veselo.ai/mcp" } } } ``` ## ChatGPT Открой [плагины ChatGPT](https://chatgpt.com/plugins), нажми «+» → «Add custom MCP server». Адрес — `https://veselo.ai/mcp`, вход — OAuth. Создай плагин и включи его в чате: ChatGPT откроет veselo.ai — войди и нажми «Разрешить». Свои MCP-серверы ChatGPT подключает в режиме разработчика (Developer mode) или на тарифах Business, Enterprise и Edu. ## Codex Терминал: ```bash codex mcp add veselo --url https://veselo.ai/mcp codex mcp login veselo ``` Вторая команда откроет veselo.ai: войди и нажми «Разрешить». ## С ключом — для программ без входа через браузер Если программа не умеет входить через браузер — или работает без человека на сервере, — передай ей ключ `sk-vsl-…` из [кабинета](https://veselo.ai/developer) в заголовке `Authorization`. ## Claude с ключом Свой коннектор с заголовком: Настройки → «Коннекторы» → «Добавить свой коннектор» (Settings → Connectors → Add custom connector), адрес — `https://veselo.ai/mcp`. В «Дополнительных настройках» (Advanced settings) в поле Request headers впиши `Authorization: Bearer sk-vsl-…`. ## Claude Desktop через mcp-remote Запасной способ — через мост `mcp-remote`, нужен установленный Node.js. Открой Settings → Developer → Edit Config и добавь в `claude_desktop_config.json`: claude_desktop_config.json: ```json { "mcpServers": { "veselo": { "command": "npx", "args": ["-y", "mcp-remote", "https://veselo.ai/mcp", "--header", "Authorization:${VESELO_AUTH}"], "env": { "VESELO_AUTH": "Bearer sk-vsl-…" } } } } ``` Перезапусти Claude Desktop. Ключ стоит в `env`, а не в `args`: так пробел после `Bearer` не ломает запуск на Windows. ## Claude Code с ключом Терминал: ```bash claude mcp add --transport http veselo https://veselo.ai/mcp --header "Authorization: Bearer $VESELO_API_KEY" ``` ## Cursor с ключом Файл `~/.cursor/mcp.json` — для всех проектов, или `.cursor/mcp.json` — в проекте: mcp.json: ```json { "mcpServers": { "veselo": { "url": "https://veselo.ai/mcp", "headers": { "Authorization": "Bearer sk-vsl-…" } } } } ``` ## VS Code с ключом Файл `.vscode/mcp.json` в проекте. Ключ VS Code спросит при первом запуске и сохранит у себя: .vscode/mcp.json: ```json { "inputs": [ { "type": "promptString", "id": "veselo-key", "description": "Ключ API Весело (sk-vsl-…)", "password": true } ], "servers": { "veselo": { "type": "http", "url": "https://veselo.ai/mcp", "headers": { "Authorization": "Bearer ${input:veselo-key}" } } } } ``` ## Codex с ключом В `~/.codex/config.toml`. Ключ Codex возьмёт из переменной окружения `VESELO_API_KEY`: config.toml: ```text [mcp_servers.veselo] url = "https://veselo.ai/mcp" bearer_token_env_var = "VESELO_API_KEY" ``` Через mcp-remote: ```text [mcp_servers.veselo] command = "npx" args = ["-y", "mcp-remote", "https://veselo.ai/mcp", "--header", "Authorization:${VESELO_AUTH}"] env = { VESELO_AUTH = "Bearer sk-vsl-…" } ``` Вариант через `mcp-remote` — для версий Codex, которые не знают поля `url`. ## Другие клиенты Клиент умеет Streamable HTTP с заголовками — укажи адрес и заголовок `Authorization`. Не умеет — запусти мост `mcp-remote`, он передаст заголовок за клиента: Терминал: ```bash npx -y mcp-remote https://veselo.ai/mcp --header "Authorization: Bearer $VESELO_API_KEY" ``` ## Для разработчиков клиентов: вход по OAuth Вход без ключа сделан по спецификации MCP Authorization — OAuth 2.1 с PKCE. Клиент, который её умеет, находит всё сам по ответу 401 от `https://veselo.ai/mcp`. | Что | Значение | |---|---| | Ответ 401 | `WWW-Authenticate: Bearer resource_metadata="https://veselo.ai/.well-known/oauth-protected-resource/mcp", scope="mcp"` | | Описание ресурса (RFC 9728) | `https://veselo.ai/.well-known/oauth-protected-resource/mcp` | | Сервер авторизации (RFC 8414) | `https://veselo.ai/.well-known/oauth-authorization-server`, issuer — `https://veselo.ai` | | Регистрация клиента (RFC 7591) | `POST https://veselo.ai/oauth/register`. Адрес возврата — https, `http://localhost` или `http://127.0.0.1` с любым портом или своя схема приложения | | Вход | `GET https://veselo.ai/oauth/authorize`: `response_type=code`, PKCE только `S256`, `resource=https://veselo.ai/mcp`. В адресе возврата — `code`, `state` и `iss` | | Токены | `POST https://veselo.ai/oauth/token` (form-urlencoded): токен доступа живёт час, токен обновления — 90 дней и меняется при каждом обновлении | | Отзыв (RFC 7009) | `POST https://veselo.ai/oauth/revoke`: отзыв токена обновления отключает программу | | Область | `mcp` | Токен годится только для `https://veselo.ai/mcp`. Шлюз `https://veselo.ai/v1` принимает только ключ `sk-vsl-…`. ## Проверить без клиента Список инструментов: ```bash curl https://veselo.ai/mcp \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' ``` Вопрос модели: ```bash curl https://veselo.ai/mcp \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "chat", "arguments": {"model": "deepseek/deepseek-v4.1-flash-ultrafast", "prompt": "Привет", "max_tokens": 100}}}' ``` Ответ: ```json { "jsonrpc": "2.0", "id": 2, "result": { "content": [{ "type": "text", "text": "Привет. Чем помочь?\n\n— deepseek/deepseek-v4.1-flash-ultrafast, 0.01 ₽" }], "structuredContent": { "text": "Привет. Чем помочь?", "model": "deepseek/deepseek-v4.1-flash-ultrafast", "cost_rub": 0.01, "usage": { "prompt_tokens": 9, "completion_tokens": 6, "total_tokens": 15, "cost_rub": 0.01 } } } } ``` --- # Справочник API Все методы API Весело: /v1/chat/completions, /v1/models, /v1/balance и /v1/usage — поля запроса и ответа, примеры JSON и коды ошибок. Базовый адрес — `https://veselo.ai/v1`. Запросы и ответы — JSON в UTF-8; у `POST` нужен заголовок `Content-Type: application/json`, без него или с неверным JSON придёт 400 `invalid_request`. Ключ — `Authorization: Bearer sk-vsl-…` или `x-api-key: sk-vsl-…`. Ошибки — в [формате OpenAI](https://veselo.ai/docs/errors), у `/v1/messages` — в формате Anthropic. | Метод | Ключ | Что делает | |---|---|---| | `POST /v1/chat/completions` | да | ответ модели — целиком или потоком | | `POST /v1/messages` | да | ответ модели в формате Anthropic — для Claude Code и SDK Anthropic | | `GET /v1/models` | нет | все модели с ценами в рублях | | `GET /v1/models/{vendor}/{model}` | нет | одна модель | | `GET /v1/balance` | да | сколько денег доступно | | `GET /v1/usage` | да | расход по дням и моделям | | `POST /v1/images/generations` | да | нарисовать картинки — ссылки или base64 и цена в рублях | | `POST /v1/audio/speech` | да | озвучить текст — в ответ MP3 | | `POST /v1/audio/music` | да | музыка по описанию — ссылка на MP3 и цена в рублях | | `POST /v1/videos` | да | запустить видео — задача | | `GET /v1/videos/{id}` | да | статус видео и ссылка на ролик | | `GET /v1/openapi.json` | нет | описание API в формате OpenAPI 3.1 | Другие адреса отвечают 404 `not_found`. MCP — отдельная точка `https://veselo.ai/mcp`, см. [MCP-сервер](https://veselo.ai/docs/mcp). ## POST /v1/chat/completions Ответ модели на список сообщений, как в OpenAI Chat Completions. Подробно — [Чат](https://veselo.ai/docs/chat), [Стриминг](https://veselo.ai/docs/streaming), [Вызов функций](https://veselo.ai/docs/tools), [Ответ в JSON](https://veselo.ai/docs/structured-output), [Картинки во входе](https://veselo.ai/docs/vision). **Поля запроса** | Поле | Тип | Что это | |---|---|---| | `model` | строка, обязательно | id модели из `GET /v1/models` | | `messages` | массив, обязательно | от 1 до 2000 сообщений `{role, content}`; роли — `system`, `user`, `assistant`, `tool` | | `stream` | true или false | ответ потоком SSE | | `max_tokens` | целое от 1 до 1 000 000 | потолок длины ответа; от него зависит удержание | | `max_completion_tokens` | целое от 1 до 1 000 000 | то же, что `max_tokens`; если заданы оба, берётся это поле | | `n` | только 1 | число вариантов ответа | | `temperature`, `top_p` | число | случайность ответа | | `top_k`, `min_p`, `top_a`, `repetition_penalty` | число | выборка у открытых моделей | | `frequency_penalty`, `presence_penalty` | число | штраф за повторы | | `stop` | строка или массив | на чём остановиться | | `seed` | целое | повторяемость ответа, если модель поддерживает | | `tools`, `tool_choice`, `parallel_tool_calls` | как у OpenAI | вызов функций | | `response_format` | объект | ответ в JSON | | `logprobs`, `top_logprobs`, `logit_bias` | как у OpenAI | вероятности токенов и их сдвиг | | `reasoning`, `reasoning_effort` | объект или строка | сколько думать моделям с рассуждениями | | `verbosity`, `prediction`, `structured_outputs` | как у модели | передаются модели как есть | Остальные поля отбрасываются без ошибки и до модели не доходят — например, `user`, `metadata`, `store`, `stream_options`, `functions`, `function_call`. Что из параметров понимает конкретная модель — в её `supported_parameters`. **Ответ** без `stream` | Поле | Что это | |---|---| | `id` | `chatcmpl-` и номер запроса `req_…` — тот же, что в заголовке `x-request-id` | | `object` | `chat.completion` | | `created` | время ответа, Unix-время | | `model` | модель, которая ответила | | `choices[0].message` | `role`, `content`, а при вызове функций — `tool_calls`; у моделей с рассуждениями может быть `reasoning` | | `choices[0].finish_reason` | `stop`, `length`, `tool_calls` или `content_filter` | | `usage.prompt_tokens`, `usage.completion_tokens`, `usage.total_tokens` | токены входа, выхода и сумма | | `usage.cost_rub` | цена запроса, ₽ | В ответе могут быть и другие поля формата OpenAI — например, подробности о токенах в `usage`. С `stream: true` ответ идёт потоком SSE, формат — в разделе [Стриминг](https://veselo.ai/docs/streaming). curl: ```bash curl -i https://veselo.ai/v1/chat/completions \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "deepseek/deepseek-v4.1-flash-ultrafast", "max_tokens": 300, "messages": [{"role": "user", "content": "Объясни в двух предложениях, что такое API."}]}' ``` Ответ: ```json { "id": "chatcmpl-req_5b2e9c0d41f84a7f9e3c2a1b0d6f8e47", "object": "chat.completion", "created": 1794132000, "model": "deepseek/deepseek-v4.1-flash-ultrafast", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "API — это правила, по которым одна программа обращается к другой…" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 19, "completion_tokens": 41, "total_tokens": 60, "cost_rub": 0.01 } } ``` **Заголовки ответа:** `x-request-id`, `x-veselo-cost-rub`, `x-veselo-balance-rub`, `x-ratelimit-*` — см. [Заголовки](https://veselo.ai/docs/headers). **Ошибки:** 400 `invalid_request`; 401 `missing_api_key`, `invalid_api_key`; 402 `insufficient_balance`; 403 `key_limit_reached`, `model_not_allowed`, `account_blocked`; 404 `model_not_found`; 413 `payload_too_large`; 422 `content_refused`; 429 `rate_limited`; 500 `internal_error`; 502 `upstream_error`; 503 `model_unavailable`, `api_disabled`; 504 `upstream_timeout`. Что значит каждая — в разделе [Ошибки](https://veselo.ai/docs/errors). ## POST /v1/messages Ответ модели в формате Anthropic Messages: обязательны `model`, `max_tokens` и `messages`. Модели, деньги и лимиты — те же, что у `/v1/chat/completions`; ошибки — в формате Anthropic. Поля, события потока и примеры — [Claude Code и формат Anthropic](https://veselo.ai/docs/anthropic). ## POST /v1/images/generations У нейросетей Студии ещё `quality` и заголовок `Idempotency-Key`; `n` — только 1. Подробно — [Картинки](https://veselo.ai/docs/images). Обязательны `model` и `prompt`; необязательны `n`, `size` или `aspect_ratio`, `response_format`, `output_format`, `seed`. Ответ: `{created, data: [{url} | {b64_json}], usage: {cost_rub}}`. Ссылки живут 7 дней. Поля, деньги, ошибки и примеры — [Картинки](https://veselo.ai/docs/images). ## POST /v1/audio/speech Обязательны `model` и `input`; необязательны `voice`, `response_format` (только mp3) и заголовок `Idempotency-Key`. Ответ — сам MP3 (`audio/mpeg`), цена — в `x-veselo-cost-rub`. Подробно — [Озвучка](https://veselo.ai/docs/speech). ## POST /v1/audio/music Обязательны `model` и `prompt`; необязательны `response_format` (url или b64_json) и заголовок `Idempotency-Key`. Ответ: `{created, data: [{url}], usage: {cost_rub}}`. Подробно — [Музыка](https://veselo.ai/docs/music). ## GET /v1/models Все модели, которые можно звать, с ценами в рублях. Ключ не нужен. Ответ — `{"object": "list", "data": [модель, …]}`; поля модели — в разделе [Модели](https://veselo.ai/docs/models#fields). curl: ```bash curl https://veselo.ai/v1/models ``` Ответ: ```json { "object": "list", "data": [ { "id": "deepseek/deepseek-v4.1-flash-ultrafast", "object": "model", "created": 1735689600, "owned_by": "deepseek", "name": "DeepSeek V4.1 Flash Ultrafast", "type": "text", "context_length": 1048576, "max_output_tokens": 16384, "input_modalities": ["text"], "output_modalities": ["text"], "pricing_rub": { "input_per_1m": 40, "output_per_1m": 120 }, "supported_parameters": ["max_tokens", "temperature", "tools", "tool_choice", "response_format", "structured_outputs"] } ] } ``` Цены в примере условные. ## GET /v1/models/{vendor}/{model} Одна модель — тот же объект, что в списке. Ключ не нужен. id со слешем пишется в путь как есть. Ошибки: 404 `model_not_found` — такой модели нет, 403 `model_not_allowed` — модель не продаётся. curl: ```bash curl https://veselo.ai/v1/models/deepseek/deepseek-v4.1-flash-ultrafast ``` ## GET /v1/balance Сколько денег доступно для запросов — по всему аккаунту. Запрос бесплатный. curl: ```bash curl https://veselo.ai/v1/balance -H "Authorization: Bearer $VESELO_API_KEY" ``` Ответ: ```json { "object": "balance", "api_balance_rub": 48.37, "held_rub": 0.12, "cashback_rub": 1.84, "available_rub": 48.25, "available": "48,25 ₽", "topup_url": "https://veselo.ai/developer/wallet" } ``` | Поле | Что это | |---|---| | `api_balance_rub` | на API-счёте, ₽; может быть чуть меньше нуля, если ответ вышел дороже удержания | | `held_rub` | удержано под идущие запросы, ₽ | | `cashback_rub` | из них кэшбэк, ₽: тратится первым, деньгами не возвращается | | `available_rub` | сколько можно потратить сейчас: свободное на API-счёте | | `topup_url` | где пополнить API-счёт | | `available` | то же строкой для людей | ## GET /v1/usage Расход по дням и моделям — по всему аккаунту. Параметр `days` — за сколько последних суток, от 1 до 90, по умолчанию 30. curl: ```bash curl "https://veselo.ai/v1/usage?days=7" -H "Authorization: Bearer $VESELO_API_KEY" ``` Ответ: ```json { "object": "usage", "days": 7, "total_rub": 3.41, "data": [ { "day": "2026-11-07", "model": "deepseek/deepseek-v4.1-flash-ultrafast", "requests": 112, "input_tokens": 254300, "output_tokens": 61840, "cost_rub": 2.86 }, { "day": "2026-11-06", "model": "deepseek/deepseek-v4.1-flash-ultrafast", "requests": 23, "input_tokens": 41200, "output_tokens": 9950, "cost_rub": 0.55 } ] } ``` | Поле | Что это | |---|---| | `days` | за сколько суток отчёт | | `total_rub` | потрачено за это время, ₽ | | `data[].day` | дата по Москве, `YYYY-MM-DD`; строки — от новых дней к старым | | `data[].model` | модель | | `data[].requests` | запросов, включая запросы с ошибкой — они стоят 0 | | `data[].input_tokens`, `data[].output_tokens` | токены входа и выхода | | `data[].cost_rub` | потрачено, ₽ | Запросы, которые ещё идут, в отчёт не попадают. ## POST /v1/videos и GET /v1/videos/{id} Видео — задача: запуск отвечает `202` с `id`, статус — `GET /v1/videos/{id}`. Поля, статусы, деньги и повторы — [Видео](https://veselo.ai/docs/video). ## GET /v1/openapi.json Описание API в формате OpenAPI 3.1 — для Postman, генераторов клиентов и ИИ-агентов. Ключ не нужен. --- # Ошибки и повторы Коды ошибок API: что значит каждый и что делать, какие запросы повторять, экспоненциальная пауза и Retry-After. Ошибка не стоит денег. Ошибки приходят в формате OpenAI, поэтому SDK OpenAI понимают их без доработок. Текст — по-русски, `code` — постоянный английский идентификатор: в коде проверяй его, а не текст. У `POST /v1/messages` ошибки — в формате Anthropic, с теми же `code` и текстами: [пример](https://veselo.ai/docs/anthropic#errors). Ответ 402: ```json { "error": { "message": "Не хватает денег на балансе для этого запроса.", "type": "billing_error", "code": "insufficient_balance", "param": null, "request_id": "req_5b2e9c0d41f84a7f9e3c2a1b0d6f8e47", "required_rub": 1.97, "available_rub": 0.4, "topup_url": "https://veselo.ai/developer/wallet" } } ``` | Поле | Что это | |---|---| | `message` | что случилось, по-русски | | `type` | класс ошибки в духе OpenAI: `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `billing_error`, `api_error` | | `code` | точная причина — из таблицы ниже | | `param` | поле запроса, которое не прошло проверку, или `null` | | `request_id` | номер запроса — назови его поддержке; он же в заголовке `x-request-id` | | `required_rub`, `available_rub`, `topup_url` | у `insufficient_balance`: сколько нужно на удержание, сколько доступно и где пополнить | | `limit_rub`, `spent_rub` | у `key_limit_reached`: месячный лимит ключа и сколько он потратил в этом месяце | | `alternatives` | у `model_unavailable`: до трёх похожих моделей, если они есть | ## Все коды | HTTP | code | Что случилось | Что делать | |---|---|---|---| | 400 | `invalid_request` | Неверный запрос: проверь поле, указанное в param. | Сверь тело запроса с документацией метода. В param — имя поля, которое не прошло проверку. | | 401 | `missing_api_key` | Нет ключа API. Выпусти его на veselo.ai/developer («Новый ключ») и передай в заголовке Authorization: Bearer sk-vsl-… | Выпусти ключ в кабинете veselo.ai/developer и передай его в заголовке Authorization. | | 401 | `invalid_api_key` | Ключ не найден или отозван. | Проверь, что ключ скопирован целиком. Отозванный ключ не оживает — выпусти новый в кабинете. | | 402 | `insufficient_balance` | Не хватает денег на балансе для этого запроса. | Пополни API-счёт в кабинете: veselo.ai/developer/wallet (баланс для роликов запросы по API не оплачивает). Или уменьши max_tokens: под запрос удерживается его наибольшая цена. | | 403 | `key_limit_reached` | Запрос не помещается в месячный лимит ключа. | Под запрос удерживается его наибольшая цена: уменьши max_tokens, подними лимит ключа в кабинете или подожди начала месяца. | | 403 | `model_not_allowed` | Эта модель у нас недоступна. | Выбери другую модель из GET /v1/models. | | 403 | `account_blocked` | Аккаунт заблокирован. | Напиши в поддержку veselo.ai. | | 404 | `model_not_found` | Модель с таким id не найдена. | Возьми id из GET /v1/models — он вида vendor/model, ровно как в поле id списка. | | 404 | `not_found` | Такого адреса в API нет. | Проверь метод и путь: базовый адрес — https://veselo.ai/v1. | | 404 | `job_not_found` | Задача не найдена. | Проверь id задачи: задачи видны только ключам того же аккаунта. | | 409 | `idempotency_conflict` | Этот Idempotency-Key уже использован с другим телом запроса. | Для нового запроса возьми новый Idempotency-Key; для повтора — то же тело. | | 413 | `payload_too_large` | Запрос слишком большой. | Тело — до 25 МБ. Большие файлы передавай ссылкой. | | 422 | `content_refused` | Запрос отклонён проверкой содержания. | Перепиши запрос: нейросеть не принимает такое содержание. Деньги не списаны. | | 429 | `rate_limited` | Слишком много запросов. | Подожди столько секунд, сколько в заголовке Retry-After, и повтори. | | 500 | `internal_error` | Что-то сломалось у нас. | Повтори через минуту. Не помогло — напиши в поддержку и приложи request_id. | | 502 | `upstream_error` | Нейросеть ответила ошибкой. | Повтори запрос или выбери другую модель. Деньги не списаны. | | 503 | `model_unavailable` | Модель сейчас недоступна. | Повтори позже или возьми модель из поля alternatives. | | 503 | `api_disabled` | API временно выключено. | Повтори позже: API включится снова. Деньги не списаны. | | 504 | `upstream_timeout` | Нейросеть не ответила вовремя. | Повтори запрос; для длинных ответов включи stream: true. | > Запрос с ошибкой не стоит денег: удержание снимается целиком. Исключение — поток, оборванный посреди ответа, см. [Стриминг](https://veselo.ai/docs/streaming#abort). Коды `job_not_found` и `idempotency_conflict` зарезервированы: сейчас их не возвращает ни один метод. ## Что повторять | Ответ | Повторять | Как | |---|---|---| | 429 `rate_limited` | да | через столько секунд, сколько в заголовке `Retry-After` | | 500 `internal_error`, 502 `upstream_error` | да | с паузой; не помогло за 3–5 попыток — напиши в поддержку и приложи `request_id` | | 503 `model_unavailable` | да | с паузой — или сразу возьми модель из `alternatives`, у неё своя цена | | 503 `api_disabled` | позже | API выключено на время: повторяй раз в несколько минут | | 504 `upstream_timeout` | да | лучше со `stream: true` или меньшим `max_tokens` | | обрыв соединения | да | с паузой; помни, что запрос без стриминга мог дойти и будет оплачен | | 402 `insufficient_balance` | нет | пополни баланс или уменьши `max_tokens`, потом повтори | | 400, 401, 403, 404, 413, 422 | нет | исправь запрос, ключ, модель или текст | ## Пауза между попытками - Есть заголовок `Retry-After` — жди столько секунд. - Нет — экспоненциальная пауза: 1, 2, 4, 8, 16 секунд плюс случайная добавка до секунды, чтобы параллельные запросы не повторялись разом. - Не больше 5 попыток, потом — ошибка наверх. - SDK OpenAI уже повторяют 429, 5xx и обрывы связи: по умолчанию 2 раза, с учётом `Retry-After`. Число повторов — `max_retries` в Python и `maxRetries` в JavaScript. ## Примеры Python: ```python import os import openai from openai import OpenAI client = OpenAI( base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"], max_retries=4, # 429, 5xx и обрывы связи SDK повторит сам, с паузой и учётом Retry-After ) try: r = client.chat.completions.create( model="deepseek/deepseek-v4.1-flash-ultrafast", messages=[{"role": "user", "content": "Объясни в двух предложениях, что такое API."}], max_tokens=300, ) print(r.choices[0].message.content, f"({r.usage.cost_rub} ₽)") except openai.APIStatusError as e: err = e.body if isinstance(e.body, dict) else {} code = err.get("code") if code == "insufficient_balance": print(f"Не хватает денег: нужно {err['required_rub']} ₽, доступно {err['available_rub']} ₽. Пополнить: {err['topup_url']}") elif code == "key_limit_reached": print(f"Запрос не помещается в месячный лимит ключа: {err['limit_rub']} ₽") elif code == "model_unavailable": print("Модель недоступна, можно взять:", err.get("alternatives")) else: print(f"Ошибка {e.status_code} {code}: {err.get('message')} (request_id {err.get('request_id')})") except openai.APIConnectionError: print("Нет связи с API — повтори позже") ``` JavaScript без SDK: ```js const RETRY = new Set([429, 500, 502, 503, 504]); const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); const backoff = (i) => Math.min(2 ** i, 30) * 1000 + Math.random() * 1000; // 1, 2, 4, 8… с async function chat(body, attempts = 5) { for (let i = 0; ; i++) { let res; try { res = await fetch('https://veselo.ai/v1/chat/completions', { method: 'POST', headers: { Authorization: `Bearer ${process.env.VESELO_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify(body), }); } catch (e) { if (i + 1 >= attempts) throw e; // нет связи await sleep(backoff(i)); continue; } if (res.ok) return res.json(); // ответ прокси может быть не JSON — тогда только код HTTP const { error } = await res.json().catch(() => ({ error: { code: `http_${res.status}`, message: res.statusText } })); if (!RETRY.has(res.status) || i + 1 >= attempts) { throw Object.assign(new Error(`${res.status} ${error.code}: ${error.message}`), { status: res.status, error }); } const after = Number(res.headers.get('retry-after')); await sleep(after > 0 ? after * 1000 : backoff(i)); } } try { const r = await chat({ model: 'deepseek/deepseek-v4.1-flash-ultrafast', max_tokens: 300, messages: [{ role: 'user', content: 'Объясни в двух предложениях, что такое API.' }], }); console.log(r.choices[0].message.content, `(${r.usage.cost_rub} ₽)`); } catch (e) { if (e.error?.code === 'insufficient_balance') console.log('Пополни баланс:', e.error.topup_url); else console.log(e.message, e.error?.request_id ?? ''); } ``` ## Если ответ — не JSON Если наш сервер недоступен, ответ может прийти от прокси — страницей HTML с кодом 502 или 504. Обрабатывай его как 502: повтори с паузой. --- # Лимиты Лимиты API Весело: 60 запросов в минуту и 10 одновременных на ключ, запрос до 25 МБ, тайм-ауты, число ключей и месячный лимит расхода. | Что | Сколько | |---|---| | Запросов в минуту | 60 на ключ, окно — последние 60 секунд | | Одновременных запросов | 10 на ключ, вместе с потоками | | Тело запроса | до 25 МБ | | Сообщений в `messages` | до 2000 | | `n` | только 1 | | `max_tokens` | целое от 1; больше `max_output_tokens` модели она не напишет | | Вход и ответ вместе | не больше `context_length` модели | | Ответ без стриминга | до 5 минут, потом 504 `upstream_timeout` | | Первый кусок потока | до 2 минут | | Тишина посреди потока | до 3 минут | | Действующих ключей | до 20 на аккаунт | | Новых ключей | до 10 в час | | Месячный лимит ключа | от 1 до 1 000 000 ₽ или без лимита; месяц — по московскому времени | | Отчёт о расходе | до 90 дней | ## Частота запросов Лимиты частоты считаются по ключу и только для `POST /v1/chat/completions` — вместе с вызовами инструмента `chat` в [MCP](https://veselo.ai/docs/mcp); список моделей, баланс и расход в них не входят. Сверх лимита придёт 429 `rate_limited` с заголовком `Retry-After` — через столько секунд освободится место. Сколько осталось, видно в заголовках каждого ответа: | Заголовок | Что это | |---|---| | `x-ratelimit-limit-requests` | лимит в минуту — 60 | | `x-ratelimit-remaining-requests` | сколько ещё можно в текущем окне | | `x-ratelimit-reset-requests` | через сколько окно освободится, например `37s` | 429 приходит и тогда, когда перегружена сама модель, — с тем же `Retry-After`. Повторяй так же. ## Много запросов сразу Держи очередь: не больше 10 запросов в полёте на ключ — лучше 8, с запасом. SDK OpenAI сам повторит запросы, которые получили 429. Python: ```python import os from concurrent.futures import ThreadPoolExecutor from openai import OpenAI client = OpenAI(base_url="https://veselo.ai/v1", api_key=os.environ["VESELO_API_KEY"], max_retries=5) questions = [f"Придумай название для кофейни номер {i}" for i in range(1, 31)] def ask(q): r = client.chat.completions.create( model="deepseek/deepseek-v4.1-flash-ultrafast", messages=[{"role": "user", "content": q}], max_tokens=50, ) return r.choices[0].message.content with ThreadPoolExecutor(max_workers=8) as pool: # не больше 8 запросов одновременно for q, a in zip(questions, pool.map(ask, questions)): print(q, "→", a) ``` JavaScript: ```js import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://veselo.ai/v1', apiKey: process.env.VESELO_API_KEY, maxRetries: 5 }); const questions = Array.from({ length: 30 }, (_, i) => `Придумай название для кофейни номер ${i + 1}`); async function ask(q) { const r = await client.chat.completions.create({ model: 'deepseek/deepseek-v4.1-flash-ultrafast', messages: [{ role: 'user', content: q }], max_tokens: 50, }); return r.choices[0].message.content; } // 8 «работников» берут вопросы из общей очереди: одновременно не больше 8 запросов const answers = []; let next = 0; await Promise.all(Array.from({ length: 8 }, async () => { while (next < questions.length) { const i = next++; answers[i] = await ask(questions[i]); } })); questions.forEach((q, i) => console.log(q, '→', answers[i])); ``` ## Тайм-ауты Ответ без стриминга ждём до 5 минут. Тайм-аут клиента ставь больше: если программа оборвёт соединение раньше, запрос всё равно доработает и будет оплачен, а повтор оплатится ещё раз. SDK OpenAI по умолчанию ждут 10 минут — этого хватает. Для долгих ответов включай `stream: true`: первый кусок ждём до 2 минут, тишину посреди потока — до 3 минут. ## Деньги Запрос не пройдёт, если на счёте не хватает на [удержание](https://veselo.ai/docs/pricing#hold) — 402, или он не помещается в [месячный лимит ключа](https://veselo.ai/docs/auth#limit) — 403. Удержание считается по `max_tokens`, поэтому не ставь его больше, чем нужно. --- # Заголовки Заголовки запроса и ответа API: ключ, номер запроса x-request-id, цена x-veselo-cost-rub, остаток, лимиты x-ratelimit, Retry-After и CORS. ## Запрос | Заголовок | Что это | |---|---| | `Authorization: Bearer sk-vsl-…` | ключ API | | `x-api-key: sk-vsl-…` | ключ для программ, которые не умеют `Authorization`, — так передают ключ SDK Anthropic; если есть оба, берётся `Authorization` | | `Content-Type: application/json` | обязателен у `POST` | | `anthropic-version`, `anthropic-beta` | у `/v1/messages` принимаем любые, не обязательны и ни на что не влияют | ## Ответ | Заголовок | Когда | Что это | |---|---|---| | `x-request-id` | всегда | номер запроса `req_…`; назови его поддержке | | `x-veselo-cost-rub` | ответ без стриминга | цена запроса, ₽, например `0.02` | | `x-veselo-balance-rub` | ответ без стриминга | сколько можно потратить после запроса, ₽: свободное на API-счёте | | `x-ratelimit-limit-requests` | `/chat/completions` | лимит запросов в минуту | | `x-ratelimit-remaining-requests` | `/chat/completions` | сколько ещё можно в текущем окне | | `x-ratelimit-reset-requests` | `/chat/completions` | через сколько окно освободится, например `37s` | | `retry-after` | 429 | через сколько секунд повторить | | `content-type` | всегда | `application/json`, у потока — `text/event-stream` | У потока заголовков с ценой и остатком нет: цена приходит в последнем куске, `usage.cost_rub`. curl: ```bash curl -s -D - -o /dev/null https://veselo.ai/v1/chat/completions \ -H "Authorization: Bearer $VESELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "deepseek/deepseek-v4.1-flash-ultrafast", "max_tokens": 50, "messages": [{"role": "user", "content": "Привет"}]}' ``` Ответ: ```text HTTP/2 200 content-type: application/json; charset=utf-8 x-request-id: req_5b2e9c0d41f84a7f9e3c2a1b0d6f8e47 x-ratelimit-limit-requests: 60 x-ratelimit-remaining-requests: 59 x-ratelimit-reset-requests: 60s x-veselo-cost-rub: 0.01 x-veselo-balance-rub: 298.24 access-control-allow-origin: * ``` ## CORS API отвечает с `Access-Control-Allow-Origin: *`, поэтому его можно звать прямо из браузера. Разрешены заголовки запроса `authorization`, `content-type`, `x-api-key`, `idempotency-key`, `http-referer`, `x-title`, `openai-organization`, `openai-project`, `anthropic-version`, `anthropic-beta`. Программе в браузере видны `x-request-id`, `x-veselo-cost-rub`, `x-veselo-balance-rub`, `retry-after` и `x-ratelimit-*`. Библиотеки, которые добавляют к запросу свои заголовки (например, `x-stainless-*` у SDK OpenAI), из браузера могут не пройти — там надёжнее обычный `fetch`, см. пример в разделе [Стриминг](https://veselo.ai/docs/streaming#examples). > Ключ в коде страницы увидит любой посетитель. Из браузера зови API только в своих инструментах, а на сайте — через свой сервер. --- # Частые вопросы Частые вопросы об API нейросетей за рубли: оплата картой и СБП, VPN, закрывающие документы, почему нет ChatGPT, Claude и Gemini. ## Это настоящие модели? Да. Запрос уходит выбранной модели, текст запроса и ответа мы не меняем. Модели запускают их создатели или компании, которые размещают открытые модели. ## Почему нет ChatGPT, Claude и Gemini? Их создатели — OpenAI, Anthropic и Google — не работают с Россией, поэтому их закрытые модели мы не продаём. Открытые модели этих компаний есть: `openai/gpt-oss-*` и `google/gemma-*` — их запускают другие компании. Остальные модели — в [каталоге](https://veselo.ai/models). ## Нужен ли VPN? Нет. API работает из России, оплата — в рублях. ## Как пополнить баланс? В [кабинете API](https://veselo.ai/developer/wallet): картой или по СБП, T-Pay, SberPay. Деньги приходят на API-счёт — он отдельный от основного баланса veselo.ai, переводов между ними нет. Подробнее — [API-счёт](https://veselo.ai/docs/pricing#wallet). ## Есть бесплатные запросы или тестовый баланс? Нет. Платишь только за запросы; запрос с ошибкой не стоит денег, а цена каждого запроса видна в ответе. ## Как получить закрывающие документы? Напиши в поддержку. ## Можно вернуть деньги с API-счёта? Неизрасходованные оплаченные деньги — да, по [условиям API](https://veselo.ai/legal/api): напиши в поддержку. Кэшбэк деньгами не возвращается. На основной баланс деньги с API-счёта не переводятся. ## Почему с баланса ушло больше, чем стоил запрос? Пока запрос идёт, на счёте удерживается его наибольшая цена. После ответа удержание снимается и списывается фактическая цена — см. [Удержание](https://veselo.ai/docs/pricing#hold). ## Почему ответ обрывается? Если `finish_reason` — `length`, модель упёрлась в `max_tokens`: подними его. Если долгий ответ приходит с ошибкой 504, включи `stream: true`. ## Что есть в API, а чего нет? Есть чат — `POST /v1/chat/completions` со стримингом, вызовом функций, ответом в JSON и картинками во входе, — тот же чат в формате Anthropic для Claude Code (`POST /v1/messages`, [подробнее](https://veselo.ai/docs/anthropic)), нейросети Студии — [картинки](https://veselo.ai/docs/images), [видео](https://veselo.ai/docs/video), [озвучка](https://veselo.ai/docs/speech) и [музыка](https://veselo.ai/docs/music), а ещё список моделей, баланс, расход и [MCP-сервер](https://veselo.ai/docs/mcp). Эмбеддингов, Batch API, Responses API, Assistants API и распознавания речи нет. ## Можно звать API из браузера? Технически да: CORS открыт. Но ключ в коде страницы увидит любой посетитель, поэтому на сайте зови API через свой сервер. ## Ключ утёк — что делать? Отзови его в [кабинете](https://veselo.ai/developer): отзыв срабатывает сразу. Выпусти новый ключ и поставь ему месячный лимит. ## Что-то сломалось — куда писать? В поддержку veselo.ai. Приложи `request_id` из ответа или заголовка `x-request-id` — по нему видно, что случилось с запросом. ## Вы храните мои запросы? Нет, текст запросов и ответов мы не храним. Подробнее — [Данные и приватность](https://veselo.ai/docs/privacy). --- # Данные и приватность Что API Весело хранит о запросах: журнал без текста запросов и ответов, ключи в виде хеша и кто обрабатывает текст запроса. Текст запросов и ответов мы не храним. Для расхода и поддержки ведём журнал без содержания. ## Что в журнале - номер запроса (`request_id`), время и длительность; - ключ, которым подписан запрос, и метод API; - модель, токены входа и выхода, цена; - код ответа и код ошибки. По журналу считается расход в кабинете и в `GET /v1/usage`, а поддержка находит запрос по `request_id`. ## Ключи Ключ проверяется по хешу. Чтобы ключ можно было показать владельцу ещё раз, он хранится и зашифрованным — секретом, которого нет в базе; показываем только после кода подтверждения. В журналах сервера ключ вырезается. ## Кто видит текст запроса Чтобы ответить, запрос передаётся компании, которая запускает выбранную модель, — в том числе иностранной. Она обрабатывает его по своим правилам; по правилам некоторых компаний данные могут храниться у них какое-то время. Имя, почта и другие данные аккаунта вместе с запросом не передаются. Не отправляй в API пароли, данные карт и персональные данные других людей. Как мы обращаемся с данными аккаунта, описано в [Политике конфиденциальности](https://veselo.ai/legal/privacy). Правила использования API, оплата и ответственность — в [условиях использования API](https://veselo.ai/legal/api). --- # Изменения Что нового в API Весело: новые методы, поля и возможности. ## Запуск - OpenAI-совместимый `POST /v1/chat/completions`: стриминг, вызов функций, ответ в JSON, картинки во входе. - Список моделей с ценами в рублях — `GET /v1/models`, без ключа. - Баланс и расход — `GET /v1/balance` и `GET /v1/usage`. - Ключи с месячным лимитом и API-счёт в копейках. - 08.11.2026: API-счёт пополняется своей оплатой и не связан с основным балансом; кэшбэк до 5% каждый месяц; ключ можно посмотреть ещё раз по коду подтверждения; ролики через API оплачиваются с API-счёта. - MCP-сервер `https://veselo.ai/mcp`. - MCP без ключа: нейросеть открывает veselo.ai, человек входит и нажимает «Разрешить» с лимитом в месяц — OAuth 2.1 с PKCE и регистрацией клиента. Подключённые нейросети и кнопка «Отключить» — в кабинете API. - Описание OpenAPI 3.1 — `GET /v1/openapi.json`. - 12.11.2026: все нейросети Студии в API — видео Seedance, Wan, Kling и MiniMax, картинки Nano Banana, GPT Image, Qwen Image и Grok Imagine с выбором качества, [озвучка](https://veselo.ai/docs/speech) `POST /v1/audio/speech` и [музыка](https://veselo.ai/docs/music) `POST /v1/audio/music`; в MCP — `generate_speech` и `generate_music`. - 13.11.2026: формат Anthropic — `POST /v1/messages`: [Claude Code](https://veselo.ai/docs/anthropic) и SDK Anthropic работают на наших открытых моделях, с потоком и инструментами. - Документация для людей и ИИ: вся она одним файлом — [llms.txt](https://veselo.ai/docs/llms.txt).