Справочник 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, у /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-сервер.
POST /v1/chat/completions
Ответ модели на список сообщений, как в OpenAI Chat Completions. Подробно — Чат, Стриминг, Вызов функций, Ответ в JSON, Картинки во входе.
Поля запроса
| Поле | Тип | Что это |
|---|---|---|
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, формат — в разделе Стриминг.
curl
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."}]}'Ответ
{
"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-* — см. Заголовки.
Ошибки: 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. Что значит каждая — в разделе Ошибки.
POST /v1/messages
Ответ модели в формате Anthropic Messages: обязательны model, max_tokens и messages. Модели, деньги и лимиты — те же, что у /v1/chat/completions; ошибки — в формате Anthropic. Поля, события потока и примеры — Claude Code и формат Anthropic.
POST /v1/images/generations
У нейросетей Студии ещё quality и заголовок Idempotency-Key; n — только 1. Подробно — Картинки.
Обязательны model и prompt; необязательны n, size или aspect_ratio, response_format, output_format, seed. Ответ: {created, data: [{url} | {b64_json}], usage: {cost_rub}}. Ссылки живут 7 дней. Поля, деньги, ошибки и примеры — Картинки.
POST /v1/audio/speech
Обязательны model и input; необязательны voice, response_format (только mp3) и заголовок Idempotency-Key. Ответ — сам MP3 (audio/mpeg), цена — в x-veselo-cost-rub. Подробно — Озвучка.
POST /v1/audio/music
Обязательны model и prompt; необязательны response_format (url или b64_json) и заголовок Idempotency-Key. Ответ: {created, data: [{url}], usage: {cost_rub}}. Подробно — Музыка.
GET /v1/models
Все модели, которые можно звать, с ценами в рублях. Ключ не нужен. Ответ — {"object": "list", "data": [модель, …]}; поля модели — в разделе Модели.
curl
curl https://veselo.ai/v1/modelsОтвет
{
"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
curl https://veselo.ai/v1/models/deepseek/deepseek-v4.1-flash-ultrafastGET /v1/balance
Сколько денег доступно для запросов — по всему аккаунту. Запрос бесплатный.
curl
curl https://veselo.ai/v1/balance -H "Authorization: Bearer $VESELO_API_KEY"Ответ
{
"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
curl "https://veselo.ai/v1/usage?days=7" -H "Authorization: Bearer $VESELO_API_KEY"Ответ
{
"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}. Поля, статусы, деньги и повторы — Видео.
GET /v1/openapi.json
Описание API в формате OpenAPI 3.1 — для Postman, генераторов клиентов и ИИ-агентов. Ключ не нужен.