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

Мы предоставляем единое OpenAI-совместимое API для ВСЕХ нейросетей, включая Anthropic, Google и пр. Для переключения на другую сеть достаточно поменять идентификатор модели (Model ID) в запросе API, интерфейсе приложения или сделав редирект модели в настройках маппинга пользователя.

Что мы поддерживаем из API?

• v1/embeddings – модель для создания текстовых эмбеддингов
• chat completions для vision-нейросетей
• генерации картинок,
• audio/transcriptions (speech to text)
• получение баланса и статуса аккаунта пользователя
• генерации голоса (TTS),

• поискового API (не OpenAI)

• кастомных ассистенты и пр. – но вы можете использовать наш пример реализации RAG (поиска по документам), если вам нужна такая функциональность.

• решения с сайта OpenAI (хотя для них есть аналоги)

Механика доступа по API и URL для подключений

• В зависимости от программы, это может быть https://api.vsegpt.ru/v1 или ещё что-то, см. примеры в Руководстве по подключению сторонних инструментов

также поддерживается старый URL на другом порту https://api.vsegpt.ru:6070/, который можно увидеть в некоторых примерах подключения

• Вы можете поменять только ID модели при запросе и перенаправить запрос к Antropic Claude, Google или опенсорс моделям, не меняя остальные поля в запросе. Мы поддерживаем единый интерфейс для всех моделей.
• Допускается указание стандартных идентификаторов gpt-3.5-turbo, gpt-4 – они будут автоматически преобразованы в соответствующие полные ID моделей OpenAI в большинстве случаев.
• Также возможно автоматическое преобразование ваших моделей в новые идентификаторы, если вы настроите маппинг моделей в Настройках

Важно: при автоматизации следуйте Правилам хорошего бота, чтобы избежать блокировки

ВАЖНО: процесс отладки вызовов по API в случае, если возникают проблемы

1. Проверка в наших сервисах

Для текстовых запросов

• Зайдите в Сервисы > Чат с o1 (просто этот чат использует нестриминговый вызов, в отличие от обычного чата, где данные выводятся стримингом по мере поступления)
• Выбираете модель model-from-sidebar
• В левой панели выбираете модель, к которой хотите обратиться.
• Запускаете запрос. Если запрос работает – значит, наше API работает.

Для других запросов (картинки и пр.)

2. Проверьте на разных моделях

• Используйте другую модель для проверки. Обычно постоянно работает openai/gpt-4o-mini
• Посмотрите на страницу Uptime и инциденты (есть в меню) – там можно посмотреть статистику по часто используемым моделям и информацию, нет ли инцидентов с какими-то моделями, мы об этом пишем
• Почитайте информацию о вашей модели на странице Моделей – может, есть какие-то особенности (например, у моделей серии OMF есть холодный старт, и они могут стать доступны в течение после 1 неуспешного запроса)

3. Получите информацию об ошибке

• Если ваш запрос не прошел валидацию в нашем API, то мы вернем 400 или 429 ошибку с описанием. Обычно проблемы простые – закончились средства на счете, нет подписки, невалиден ключ и пр. Этот запрос не будет зарегистрирован в системе.
• Если ваш запрос прошел наше API и ушел поставщику нейросети, его статус и текст ошибки будет доступен в меню Кабинет > Стоимость последних генераций. Можете использовать его.

4. Обратитесь к отладочной точке доступа, чтобы посмотреть ваш запрос

Пример вызова API (Python, CURL)

Генерация текста (chat/completions)

from openai import OpenAI

client = OpenAI(
    api_key="sk-XXXXXXXXXXXXXXXX", # ваш ключ в VseGPT после регистрации
    base_url="https://api.vsegpt.ru/v1",
)

prompt = "Напиши последовательно числа от 1 до 10"

messages = []
#messages.append({"role": "system", "content": system_text})
messages.append({"role": "user", "content": prompt})

response_big = client.chat.completions.create(
    model="anthropic/claude-3-haiku", # id модели из списка моделей - можно использовать OpenAI, Anthropic и пр. меняя только этот параметр
    messages=messages,
    temperature=0.7,
    n=1,
    max_tokens=3000, # максимальное число ВЫХОДНЫХ токенов. Для большинства моделей не должно превышать 4096
    extra_headers={ "X-Title": "My App" }, # опционально - передача информация об источнике API-вызова
)

#print("Response BIG:",response_big)
response = response_big.choices[0].message.content
print("Response:",response)

import openai

openai.api_key = "sk-XXXXXXXXXXXXXXXX" # ваш ключ в VseGPT после регистрации

openai.api_base = "https://api.vsegpt.ru/v1"

prompt = "Напиши последовательно числа от 1 до 10"

messages = []
#messages.append({"role": "system", "content": system_text})
messages.append({"role": "user", "content": prompt})

response_big = openai.ChatCompletion.create(
    model="anthropic/claude-instant-v1", # id модели из списка моделей - можно использовать OpenAI, Anthropic и пр. меняя только этот параметр
    messages=messages,
    temperature=0.7,
    n=1,
    max_tokens=3000, # максимальное число ВЫХОДНЫХ токенов. Для большинства моделей не должно превышать 4096
    headers={ "X-Title": "My App" }, # опционально - передача информация об источнике API-вызова    
)

#print("Response BIG:",response_big)
response = response_big["choices"][0]["message"]
print("Response:",response)

curl https://api.vsegpt.ru/v1/chat/completions
  -H "Content-Type: application/json"
  -H "Authorization: Bearer $VSEGPT_API_KEY"
  -d '{
    "model": "openai/gpt-3.5-turbo",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

Генерация Embedding

from openai import OpenAI
client = OpenAI(
  api_key="sk-XXXXXXXXXXXXXXXX", # ваш ключ в VseGPT после регистрации
  base_url="https://api.vsegpt.ru/v1",
)

client.embeddings.create(
  model="text-embedding-ada-002",
  input="The food was delicious and the waiter...",
  encoding_format="float"
)

import openai

openai.api_key = "sk-XXXXXXXXXXXXXXXX" # ваш ключ в VseGPT после регистрации

openai.api_base = "https://api.vsegpt.ru/v1"

response_big = openai.Embedding.create(
    model="text-embedding-ada-002",
    input="function add(a, b) { return a + b; }",
)

print("Response BIG:",response_big)
res = response_big["data"][0]["embedding"]

curl https://api.vsegpt.ru/v1/embeddings
  -H "Authorization: Bearer $VSEGPT_API_KEY"
  -H "Content-Type: application/json"
  -d '{
    "input": "The food was delicious and the waiter...",
    "model": "text-embedding-ada-002",
    "encoding_format": "float"
  }'

Embedding в LangChain

from langchain_openai import OpenAIEmbeddings

model = OpenAIEmbeddings(model="text-embedding-3-large", openai_api_base = "https://api.vsegpt.ru/v1/")

https://api.python.langchain.com/en/latest/embeddings/langchain_openai.embeddings.base.OpenAIEmbeddings.html

Vision-модель (текст+картинка -> текст)

from openai import OpenAI
client = OpenAI(
    api_key="sk-XXXXXXXXXXXXXXXX", # ваш ключ в VseGPT после регистрации
    base_url="https://api.vsegpt.ru/v1",
)

response = client.chat.completions.create(
    model="vis-google/gemini-flash-1.5",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What you think the person in the image is doing?"},
                {
                    "type": "image_url",
                    "image_url": "https://img-s-msn-com.akamaized.net/tenant/amp/entityid/AA18Lnc8.img?w=1920&h=1080&q=60&m=2&f=jpg",
                },
            ],
        }
    ],
    max_tokens=400,
)

print(response.choices[0])

import openai

openai.api_key = "sk-XXXXXXXXXXXXXXXX" # ваш ключ в VseGPT после регистрации

openai.api_base = "https://api.vsegpt.ru/v1"

messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What you think the person in the image is doing?"},
                {
                    "type": "image_url",
                    "image_url": "https://img-s-msn-com.akamaized.net/tenant/amp/entityid/AA18Lnc8.img?w=1920&h=1080&q=60&m=2&f=jpg",
                },
            ],
        }
    ]

response_big = openai.ChatCompletion.create(
    model="vis-google/gemini-flash-1.5",
    messages=messages,
    temperature=0.8,
    n=1,
    max_tokens=300,
)

#print("Response BIG:",response_big)
response = response_big["choices"][0]["message"]
print("Response:",response)

curl https://api.vsegpt.ru/v1/chat/completions
  -H "Content-Type: application/json"
  -H "Authorization: Bearer $VSEGPT_API_KEY"
  -d '{
    "model": "vis-google/gemini-flash-1.5",
    "messages": [
      {
        "role": "user",
        "content": [
                {"type": "text", "text": "What you think the person in the image is doing?"},
                {
                    "type": "image_url",
                    "image_url": "https://img-s-msn-com.akamaized.net/tenant/amp/entityid/AA18Lnc8.img?w=1920&h=1080&q=60&m=2&f=jpg"
                }
        ]
      }
    ],
    "max_tokens": 400
  }'

import openai
import base64

def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")


openai.api_key = "sk-XXXXXXXXXXXXXXXX" # ваш ключ в VseGPT после регистрации

openai.api_base = "https://api.vsegpt.ru/v1"

base64_image = encode_image("Einstein.jpg")
messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What you think the person in the image is doing?"},
                {
                    "type": "image_url",
                    "image_url": f"data:image/jpeg;base64,{base64_image}",
                },
            ],
        }
    ]

response_big = openai.ChatCompletion.create(
    model="vis-google/gemini-pro-vision",
    messages=messages,
    temperature=0.8,
    n=1,
    max_tokens=300,
)

#print("Response BIG:",response_big)
response = response_big["choices"][0]["message"]
print("Response:",response)

Генерация изображения

from openai import OpenAI
client = OpenAI(
  api_key="sk-XXXXXXXXXXXXXXXX", # ваш ключ в VseGPT после регистрации
  base_url="https://api.vsegpt.ru/v1",
)

client.images.generate(
  model="dall-e-3",
  prompt="An astronaut riding the horse on the Moon.",
  n=1,
  size="1024x1024"
)

import openai

openai.api_key = "sk-XXXXXXXXXXXXXXXX" # ваш ключ в VseGPT после регистрации

openai.api_base = "https://api.vsegpt.ru/v1"

response_big = openai.Image.create(
    model="dall-e-2",
    prompt="An astronaut riding the horse on the Moon.",
    n=1,
    size="1024x1024",
    quality="standard"
)

print(response_big)

curl https://api.vsegpt.ru/v1/images/generations   
  -H "Content-Type: application/json"   
  -H "Authorization: Bearer $VSEGPT_API_KEY"   
  -d '{
    "model": "dall-e-3",
    "prompt": "An astronaut riding the horse on the Moon.",
    "n": 1,
    "size": "1024x1024"
  }'

Распознавание речи

from openai import OpenAI
client = OpenAI(
  api_key="sk-XXXXXXXXXXXXXXXX", # ваш ключ в VseGPT после регистрации
  base_url="https://api.vsegpt.ru/v1",
)

audio_file = open("speech.mp3", "rb")
transcript = client.audio.transcriptions.create(
  model = "stt-openai/whisper-1",
  response_format="text",
  language="ru", # опционально, может быть пустым
  file=audio_file
)

import openai

openai.api_key = "sk-XXXXXXXXXXXXXXXX" # ваш ключ в VseGPT после регистрации

openai.api_base = "https://api.vsegpt.ru/v1"

with open("test_rec.mp3", "rb") as audio_file:
    transcript = openai.Audio.transcribe(
        file = audio_file,
        model = "stt-openai/whisper-1",
        response_format="text", # опционально, может быть пустым
        language="ru",
    )
print(transcript.get("text"))

curl https://api.vsegpt.ru/v1/audio/transcriptions
  -H "Authorization: Bearer $VSEGPT_API_KEY"
  -H "Content-Type: multipart/form-data"
  -F file="@/path/to/file/audio.mp3"
  -F model="stt-openai/whisper-1"

Генерация речи (Text-to-Speech)

from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key="sk-XXXXXXXXXXXXXXXX", # ваш ключ в VseGPT после регистрации
    base_url="https://api.vsegpt.ru/v1",
)

speech_file_path = Path(__file__).parent / "speech.mp3"
response = client.audio.speech.create(
    model="tts-openai/tts-1",
    voice="nova", # поддерживаются голоса alloy, echo, fable, onyx, nova и shimmer
    input="Сегодня на улице очень жарко, не так ли?",
    # response_format="wav" # другой формат, при необходимости
)

response.write_to_file(speech_file_path)

curl https://api.vsegpt.ru/v1/audio/speech
  -H "Authorization: Bearer $VSEGPT_API_KEY"
  -H "Content-Type: application/json"
  -d '{
    "model": "tts-1",
    "input": "The quick brown fox jumped over the lazy dog.",
    "voice": "alloy"
  }'
  --output speech.mp3

Генерация видео (Text-to-Video)

• Сначала идет обращение на /v1/video/generate – ставим задачу на генерацию видео, получаем request_id в ответе.
• Далее каждые 10 секунд (можно больше) обращаемся на /v1/video/status?request_id=<request_id> и api key для получения статуса и URL результата.
• Когда status=COMPLETED, можно получить URL и по нему скачать видео

import requests
import json
import time
from datetime import datetime, timedelta

api_key = "your_vsegpt_api_key"

def generate_and_wait_video(prompt, model_id="txt2vid-kling/standart", aspect_ratio="16:9",
                            timeout_minutes=20):
    base_url = "https://api.vsegpt.ru/v1/video"

    # Заголовки запроса для генерации
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    # Тело запроса
    payload = {
        "model": model_id,
        "action": "generate",
        "prompt": prompt,
        "aspect_ratio": aspect_ratio
    }

    # Запоминаем время начала генерации
    start_time = datetime.now()

    # Выполнение POST запроса для генерации
    response = requests.post(
        url=f"{base_url}/generate",
        headers=headers,
        json=payload
    )

    # Проверка статус кода
    if response.status_code != 200:
        print('ERROR', response.status_code, response.text)
        return

    # Получение request_id
    response_data = response.json()
    request_id = response_data.get('request_id')

    if not request_id:
        raise Exception("Failed to get request_id")

    print(f"Generation started with request_id: {request_id}")
    print(f"Using model: {model_id}")
    print(f"Aspect ratio: {aspect_ratio}")

    # Заголовки для проверки статуса
    status_headers = {
        "Authorization": f"Key {api_key}"
    }

    # Установка времени окончания ожидания
    timeout_time = datetime.now() + timedelta(minutes=timeout_minutes)

    # Цикл проверки статуса
    while datetime.now() < timeout_time:
        # Запрос статуса
        status_response = requests.get(
            url=f"{base_url}/status?request_id={request_id}",
            headers=status_headers
        )

        status_data = status_response.json()
        status = status_data.get('status')
        video_url = status_data.get('url')

        # Вычисляем прошедшее время
        elapsed_time = datetime.now() - start_time
        elapsed_minutes = elapsed_time.total_seconds() / 60

        print(f"Current status: {status} (Elapsed time: {elapsed_minutes:.1f} minutes)")

        if status == 'COMPLETED':
            print(f"Video generated successfully!")
            print(f"Total generation time: {elapsed_minutes:.1f} minutes")
            print(f"Video URL: {video_url}")
            return video_url

        elif status == 'FAILED':
            raise Exception(f"Video generation failed after {elapsed_minutes:.1f} minutes")

        # Ждем 10 секунд перед следующей проверкой
        time.sleep(10)

    # Если вышли из цикла по таймауту
    elapsed_time = datetime.now() - start_time
    elapsed_minutes = elapsed_time.total_seconds() / 60
    raise Exception(f"Timeout after {elapsed_minutes:.1f} minutes")

# Примеры использования
try:
    # Использование с указанием конкретной модели
    video_url = generate_and_wait_video(
        prompt="Panda playing guitar in the middle of Paris.",
        model_id="txt2vid-kling/standart",
        aspect_ratio="9:16"

    )

    # Использование с указанием модели и таймаута
    # video_url = generate_and_wait_video(
    #     prompt="Panda playing guitar in the middle of Manhattan.",
    #     model_id="txt2vid-kling/standart",
    #     timeout_minutes=30
    # )

except Exception as e:
    print(f"Error: {e}")

Генерация видео по картинке (Image-to-Video)

def encode_image_to_base64(image_file):
    """Кодирует загруженное изображение в base64"""
    return base64.b64encode(image_file.read()).decode('utf-8')

# Добавляем в JSON запроса указание картинки
payload["image_url"] = f"data:image/jpeg;base64,{image_base64}"

Генерация музыки (Text-to-Audio)

from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key="sk-XXXXXXXXXXXXXXXX", # ваш ключ в VseGPT после регистрации
    base_url="https://api.vsegpt.ru/v1",
)

response = client.audio.speech.create(
    extra_body={
        "seconds_total": 10 # число секунд для генерации
    },
    voice="nova", # не используется, но требуется библиотекой
    model="tta-stable/stable-audio",
    response_format="wav", # всегда WAV, другие не поддерживаются
    input="128 BPM, techno drum music",
)


response.write_to_file(music_wav_file)

curl https://api.vsegpt.ru/v1/audio/speech
  -H "Authorization: Bearer $VSEGPT_API_KEY"
  -H "Content-Type: application/json"
  -d '{
    "model": "tta-stable/stable-audio",
    "input": "128 BPM, techno drum music",
    "seconds_total": 10
  }'
  --output music.wav

Получение баланса (Python)

настройках пользователя

{
 "status":"ok", # общий статус запроса
 "data":{
   "credits":"10.752448", # остаток на балансе
   "subscription_status":"ok", # статус подписки (должен быть ok - это означает, что подписка работает)
   "subscription_end":"2024-05-02 00:08:02" # формальное время окончания подписки, МСК
   "user_status":1, # статус пользователя 0 - green, 1 - yellow (меньше средств, чем указано в настройках), 2 - red (аккаунт неработоспособен). 
   "user_status_text":"Less than 500 credits on account. " # в случае, если status не 0 - причина.
}}

import requests
    import json
    response = requests.get(
        url="https://api.vsegpt.ru/v1/balance",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        },
    )

    # print(response.text)

    if response.status_code == 200:
        response_big = json.loads(response.text)
        if response_big.get("status") == "ok":
            credits = float(response_big.get("data").get("credits"))
        else:
            raise response_big.get("reason") # reason of error
    else:
        raise ValueError(str(response.status_code) + ": " + response.text)

Получение информации о доступных моделях

https://api.vsegpt.ru/v1/models

Сторонние библиотеки и примеры на других языках (CURL, NodeJS)

Библиотека для работы с VseGPT для Go

https://github.com/saintbyte/vsegpt_api

Опенсорс примеры

Демо: телеграм-бот, отвечающий на вопросы

https://github.com/janvarev/Telegram-bot-vsegpt

Демо: RAG (поиск по базе знаний / серии документов с помощью эмбеддингов и векторной базы данных)

https://github.com/janvarev/demo_rag_vsegpt

Как сделать сервис «Вопросы по файлу»

context_prompt = f"""Here's an article:\n\n<article>
        {article}\n\n</article>\n\n"""
context_message = {"role": "system", "content": context_prompt}
question_message = {"role": "user", "content": "Напиши краткое содержание данной статьи"}

Опенсорс: телеграм-бот Киберникто

https://github.com/solovieff/kibernikto

Ошибки API и их обработка

Общие принципы

• 200 – все ОК 
• 4xx – что-то не ОК
• 504 – (EDGE_FUNCTION_INVOCATION_TIMEOUT) – сервер не смог ответить в нужное время. Попробуйте тупо переотправить запрос повторно. (Редко бывают периоды, когда сервера перегружены и таких ошибок бывает до 10%)
• 500 – ошибка сервера. Либо у нас всё плохо (маловероятно), либо вы некорректно сформировали запрос по API (очень вероятно)

Вебчат: Failed to fetch

Ошибка 400 (большинство обычных ошибок)

• если вы долго ведете чат – начните новый чат! Чтобы нейросеть понимала контекст разговора, при запросе обрабатываются ВСЕ предыдущие сообщения чата как входные данные. Поэтому, если вы начинаете НОВУЮ ТЕМУ разговора, начинайте НОВЫЙ чат без истории диалога – это сэкономит вам массу средств.
• или перейдите на другую модель с более большим размером контекста

Ошибка 403

Ошибка 429

Ошибка 500, 502 (EDGE_FUNCTION_INVOCATION_FAILED или INTERNAL_SERVER_ERROR или пусто)

• Сервер временно недоступен, какие-то проблемы у нас (маловероятно)
• Вы некорректно отправляете API запрос. EDGE_FUNCTION_INVOCATION_FAILED возвращает наш вышестоящий провайдер, означает, что с вызовом API что-то не так, но что именно, сказать невозможно. Попробуйте отладить API-запрос.

Ошибка 504 (EDGE_FUNCTION_INVOCATION_TIMEOUT)

Особенности реализации

Поддерживаемые endpoints

Поддержка function calls (УСТАРЕЛО)

С 20 августа функциональность function calls, как устаревшая версия tool calls, больше не работает. Пожалуйста, используйте tool calls для реализации.

https://openai.com/blog/function-calling-and-other-api-updates

https://cookbook.openai.com/examples/how_to_call_functions_with_chat_models

• OpenAI openai/gpt-3.5-turbo, gpt4, и, возможно другие (ответ будет в элементе function_call)
• jondurbin/airoboros-l2–70b (ответ будет в элементе content)

#
    prompt = "What is the weather like in Boston?"

    messages = []
    #messages.append({"role": "system", "content": system_text})
    messages.append({"role": "user", "content": prompt})

    response = openai.ChatCompletion.create(

        model="openai/gpt-3.5-turbo",
        # model="jondurbin/airoboros-l2-70b",
        messages =messages,
        temperature=0.9,
        n=1,
        max_tokens = 1500,
        stream=stream,
        functions=[
            {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"]
                        }
                    },
                    "required": ["location"]
                }
            }
        ]
    )

Поддержка tools (РЕКОМЕНДУЕТСЯ, поддерживаются и другие модели в при записи tools в OpenAI-формате)

#
    prompt = "What is the weather like in Boston?"

    messages = []
    #messages.append({"role": "system", "content": system_text})
    messages.append({"role": "user", "content": prompt})

    response = openai.ChatCompletion.create(

        model="openai/gpt-3.5-turbo",
        messages =messages,
        temperature=0.1,
        n=1,
        max_tokens = 1500,
        stream=False,
        tool_choice="auto",
        tools = [{
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA",
                        },
                        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                    },
                    "required": ["location"],
                },
            },
        }
        ]
    )

n=1

Неуказанные max_tokens в chat/completions

странице настроек