Справочник по API

Быстрая справка

Requests

Completions Request Format

Запросы к /v1/chat/completions совместимы с форматом OpenAI Chat API (см. quickstart).

Тело запроса (TypeScript):

type Request = {
  // Обязательно: messages или prompt
  messages?: Message[];
  prompt?: string;

  // Если model не указан, используется дефолтный пользователя
  model?: string;

  // Формат ответа (JSON / JSON Schema)
  response_format?: ResponseFormat;

  stop?: string | string[];
  stream?: boolean;

  // Параметры генерации
  max_tokens?: number;    // [1, context_length)
  temperature?: number;   // [0, 2]
  top_p?: number;         // (0, 1]
  top_k?: number;         // [1, Infinity)
  frequency_penalty?: number;  // [-2, 2]
  presence_penalty?: number;   // [-2, 2]
  repetition_penalty?: number; // (0, 2]
  min_p?: number;         // [0, 1]
  top_a?: number;         // [0, 1]
  seed?: number;
  logit_bias?: { [key: number]: number };

  // Tool calling
  tools?: Tool[];
  tool_choice?: ToolChoice;

  // Суффиксы маршрутизации (добавляются к имени модели)
  // :nitro → provider.sort = "throughput"
  // :floor → provider.sort = "price"

  // OpenRouter-специфичные параметры
  provider?: ProviderPreferences;
  user?: string;
};

type Message = {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string | ContentPart[];
  name?: string;
  tool_call_id?: string; // для role: 'tool'
};

type ContentPart = 
  | { type: 'text'; text: string }
  | { type: 'image_url'; image_url: { url: string; detail?: string } };

type Tool = {
  type: 'function';
  function: {
    description?: string;
    name: string;
    parameters: object;
  };
};

type ToolChoice = 'none' | 'auto' | { type: 'function'; function: { name: string } };

type ResponseFormat = 
  | { type: 'json_object' }
  | { type: 'json_schema'; json_schema: { name: string; strict?: boolean; schema: object } };

type ProviderPreferences = {
  order?: string[];     // Приоритет провайдеров
  ignore?: string[];    // Игнорируемые провайдеры
  sort?: 'throughput' | 'price';  // Стратегия сортировки
};

Headers

Structured Outputs

Через response_format:

• { type: 'json_object' } — базовый JSON-режим
• { type: 'json_schema', json_schema: { name, strict, schema } } — строгая схема

Assistant Prefill

Поддерживается нативно через последнее сообщение с role: "assistant":

{
  "messages": [
    { "role": "user", "content": "Что такое ИИ?" },
    { "role": "assistant", "content": "ИИ — это" }
  ]
}

Поддержка Responses API (OpenAI)

Эндпоинт /v1/responses принимает поле input вместо messages:

{
  "model": "openai/gpt-4o",
  "input": "Расскажи о себе"
}

input может быть строкой или массивом structured input. Конвертируется в messages автоматически.

Responses

Формат ответа

OpenRouter возвращает ответы в формате, совместимом с OpenAI Chat API:

type Response = {
  id: string;
  choices: (NonStreamingChoice | StreamingChoice)[];
  created: number;
  model: string;
  object: 'chat.completion' | 'chat.completion.chunk';
  usage?: ResponseUsage;
};

type NonStreamingChoice = {
  finish_reason: string | null;
  native_finish_reason: string | null;
  message: {
    content: string | null;
    role: string;
    tool_calls?: ToolCall[];
  };
};

type StreamingChoice = {
  finish_reason: string | null;
  native_finish_reason: string | null;
  delta: {
    content?: string | null;
    role?: string;
    tool_calls?: ToolCall[];
  };
};

type ResponseUsage = {
  prompt_tokens: number;
  completion_tokens: number;
  total_tokens: number;
  prompt_tokens_details?: {
    cached_tokens: number;
    cache_write_tokens?: number;
  };
  completion_tokens_details?: {
    reasoning_tokens?: number;
  };
  cost?: number;                    
  currency?: string;                
};

Finish Reason

Нормализованные значения: tool_calls, stop, length, content_filter, error.

Оригинальное значение провайдера доступно в native_finish_reason.

Пример ответа

{
  "id": "gen-xxxxxxxxxxxxxx",
  "choices": [
    {
      "finish_reason": "stop",
      "native_finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Привет!"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 4,
    "total_tokens": 14,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_cost": 0.00014,
    "currency": "RUB"
  }
}

Эндпоинты

GET /v1/health

Проверка работоспособности. Не требует аутентификации.

{
  "status": "ok",
  "version": "1.0",
  "endpoints": [
    "models", "embeddings/models", "rerank/models",
    "images/models", "audio/models", "tts/models",
    "transcriptions/models", "chat/completions",
    "completions", "embeddings", "responses",
    "rerank", "images/generations", "images",
    "audio/speech", "audio/transcriptions", "audio/translations",
    "user/balance", "generation"
  ]
}

POST /v1/embeddings

Генерация векторных представлений текста (эмбеддингов).

Параметры:

Пример:

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

POST /v1/images/generations

Генерация изображений. Поддерживает image-to-image (через image или input_references).

Параметры:

Пример:

curl https://api.ru-openrouter.ru/v1/images/generations \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/dall-e-3",
    "prompt": "Кот в космосе, цифровой арт",
    "n": 1,
    "image_config": {
      "aspect_ratio": "16:9",
      "image_size": "2K"
    }
  }'

POST /v1/images

Алиас для /v1/images/generations.

POST /v1/audio/speech

Синтез речи из текста. Возвращает аудиофайл.

Параметры:

Пример:

curl https://api.ru-openrouter.ru/v1/audio/speech \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/tts-1",
    "input": "Привет! Это пример синтеза речи.",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

POST /v1/audio/transcriptions

Распознавание речи из аудиофайла. Поддерживает два формата:

• multipart/form-data: model + file (OpenAI-стиль)
• application/json: model + input_audio.data (base64) + input_audio.format (OpenRouter-стиль)

Параметры:

POST /v1/audio/translations

Перевод аудио на английский. Аналогичен транскрипции по формату.

POST /v1/rerank

Реранкинг документов по релевантности запросу.

Параметры:

Пример:

curl https://api.ru-openrouter.ru/v1/rerank \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere/rerank",
    "query": "Что такое искусственный интеллект?",
    "documents": [
      "ИИ — это область компьютерных наук...",
      "Машинное обучение — подраздел ИИ..."
    ],
    "top_n": 2
  }'

POST /v1/videos

Асинхронная генерация видео. Создаёт задачу, возвращает job_id.

Параметры:

Пример:

curl -X POST https://api.ru-openrouter.ru/v1/videos \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/sora",
    "prompt": "A serene lake at sunset with mountains"
  }'

GET /v1/videos?id={job_id}

Получение статуса и результата видео-задачи.

GET /v1/videos/history

Список завершённых видео пользователя.

GET /v1/videos/content?id={job_id}

Скачивание готового видеофайла.

GET /v1/user/balance

Текущий баланс пользователя.

{
  "user": "user@example.com",
  "balance": 150.50,
  "currency": "RUB"
}

GET /v1/generation

Логи использования API.

Параметры:

Ответ:

{
  "logs": [
    {
      "id": 12345,
      "model_name": "openai/gpt-4o-mini",
      "input_tokens": 100,
      "output_tokens": 50,
      "total_cost": 0.15,
      "timestamp": "2025-03-11T12:00:00Z"
    }
  ],
  "total": 1
}

Коды ошибок