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

Idezo — OpenAI-совместимый HTTP API к языковым моделям с оплатой в рублях. Меняете base_url и ключ — остальной код SDK не трогаете.

Быстрый старт

1. Зарегистрируйтесь на сайте и откройте кабинет.
2. Выпустите ключ idz_… (показывается один раз).
3. Отправляйте запросы на базовый URL ниже с заголовком Authorization: Bearer ….

Базовый URL

https://idezo.ru/api/v1

Пример curl

curl https://idezo.ru/api/v1/chat/completions \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Привет"}]
  }'

Авторизация

Все эндпоинты /api/v1/* требуют ключ Idezo в заголовке:

Authorization: Bearer idz_…

Ключ создаётся и удаляется в кабинете (до 10 штук). Полное значение видно только сразу после выпуска — сохраните его. Не передавайте ключ во фронтенд и публичные репозитории.

Модели

Идентификатор модели — короткое имя без префикса провайдера (например gpt-4o-mini, claude-sonnet-5, gemini-2.5-flash). Актуальный список и цены — на странице Цены; тот же каталог доступен через API.

GET /models

curl https://idezo.ru/api/v1/models \
  -H "Authorization: Bearer "

Ответ (фрагмент)

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "owned_by": "openai"
    }
  ]
}

В chat/completions поле model должно точно совпадать с id из каталога. Неизвестная модель → 404 model_not_found.

Chat completions

Основной эндпоинт генерации текста. Формат запроса и ответа совместим с OpenAI Chat Completions.

POST /chat/completions

{
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "system", "content": "Отвечай кратко."},
    {"role": "user", "content": "Что такое Idezo?"}
  ],
  "temperature": 0.7,
  "max_tokens": 256,
  "stream": false
}

Успешный ответ (фрагмент)

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "gpt-4o-mini-2024-07-18",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "…"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 40,
    "total_tokens": 60
  }
}

Списание идёт по usage.prompt_tokens и usage.completion_tokens по тарифу модели.

Embeddings

Векторные представления текста. Списание только за входные токены (в таблице цен колонка «Выход» = 0). Модель: text-embedding-3-small.

POST /embeddings

curl https://idezo.ru/api/v1/embeddings \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "текст для векторизации"
  }'

Python

r = client.embeddings.create(
    model="text-embedding-3-small",
    input="текст для векторизации",
)
print(len(r.data[0].embedding))

Изображения

Генерация: POST /images/generations (JSON). Редактирование: POST /images/edits (multipart). Модели: gpt-image-2, gpt-image-1.5, nano-banana-2, nano-banana-pro, aigc-image-kling-3.0. Midjourney — отдельный путь /api/mj/…, не этот эндпоинт.

POST /images/generations

curl https://idezo.ru/api/v1/images/generations \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"кот в космосе","n":1}'

URL картинки в ответе — https://idezo.ru/api/v1/files/… (скачивается без ключа, 7 суток). Списание: n × цена модели после HTTP 2xx.

Аудио

POST /audio/transcriptions и /audio/translations — Whisper, multipart, файл до 50 МБ. Suno: POST /api/suno/submit/music и GET /api/suno/fetch/{id}.

Whisper

curl https://idezo.ru/api/v1/audio/transcriptions \
  -H "Authorization: Bearer " \
  -F file=@audio.mp3 \
  -F model=whisper-1

Видео

Задача создаётся сразу, клиент сам поллит статус. Kling и Veo (aigc-video-gv-3.1*): POST /api/v1/video/generations → GET /api/v1/video/generations/{id}. Wan text-to-video — тот же путь. Wan image-to-video: POST /api/alibailian/api/v1/services/aigc/video-generation/video-synthesis → GET /api/alibailian/api/v1/tasks/{id}. Seedance: POST /api/volc/v1/contents/generations/tasks → GET …/tasks/{id}.

Нет duration — считаем 5 секунд. Query бесплатный. Если задача упала (failed / FAILURE / error) — деньги возвращаем один раз.

Streaming

Передайте "stream": true. Ответ — text/event-stream (SSE), чанки в формате OpenAI. В конце приходит usage (Idezo запрашивает stream_options.include_usage автоматически) и строка data: [DONE].

curl https://idezo.ru/api/v1/chat/completions \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "gpt-4o-mini",
    "stream": true,
    "messages": [{"role": "user", "content": "Привет"}]
  }'

Биллинг

Баланс в рублях. Новому аккаунту начисляется 100 ₽. Текст и эмбеддинги — по usage токенов. Картинки, видео, аудио, MJ, Suno, /responses — по оценке после HTTP 2xx (см. Цены).

Перед запросом проверяется баланс. Если средств недостаточно — 402 insufficient_quota, upstream не вызывается. Картинка: n × цена. Видео: секунды × цена (по умолчанию 5). Whisper/Suno/MJ: 1 вызов. Упавшая async-задача — возврат при poll.

Ошибки

Тело ошибки:

{
  "error": {
    "message": "человекочитаемый текст",
    "type": "код",
    "code": "код"
  }
}

Частые коды

401 invalid_api_key — нет или неверный Bearer-ключ
402 insufficient_quota — недостаточно средств
404 model_not_found — модель не из каталога Idezo
400 invalid_request_error — битый JSON / нет model
404 task_not_found — чужая или неизвестная задача
502 upstream_error / ответы upstream с их HTTP-кодом

SDK

Любой OpenAI-совместимый клиент: укажите base URL Idezo и ключ idz_….

Python (openai)

from openai import OpenAI

client = OpenAI(
    api_key="idz_…",
    base_url="https://idezo.ru/api/v1",
)

r = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Привет"}],
)
print(r.choices[0].message.content)

Node.js (openai)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.IDEZO_API_KEY,
  baseURL: "https://idezo.ru/api/v1",
});

const r = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Привет" }],
});
console.log(r.choices[0].message.content);

Ограничения

OpenAI SDK (base_url=https://idezo.ru/api/v1): /models, /chat/completions (stream), /embeddings, /images/generations, /images/edits, /audio/transcriptions, /audio/translations, /responses.
Видео и native: /api/v1/video/generations, /api/v1/video/create, /api/alibailian/…, /api/volc/…, /api/mj/…, /api/suno/…. Список задач MJ с площадки не проксируется.
Картинка во входе chat — URL в messages (тело chat до 8 МБ). Multipart — до 50 МБ.
GET /models отдаёт все kind. Не вызывайте mj_imagine через chat.
До 10 API-ключей на аккаунт.
Контент моделей подчиняется правилам провайдеров; ответственность за промпты и использование — на клиенте.