• Основные концепции API
• Примеры кода (Python, CURL, Google Colab и пр.)
• Опенсорс примеры (RAG, телеграм-бот и пр.)
• Решение проблем API и список ошибок
• Особенности реализации API
• Дополнительные возможности (Tools, MCP и пр.)

ГОТОВЫЕ ПРИМЕРЫ в Google Colab

Ссылки на блокноты с примерами

• Базовый пример – вызов gpt-4o-mini
• Работа с большим текстом – поиск по текстовой базе знаний с помощью эмбеддингов (RAG)

Пример вызова 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 requests
import json

# Выполнение POST запроса
response = requests.post(
    "https://api.vsegpt.ru/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {VSEGPT_KEY}",
        "Content-Type": "application/json",
        "X-Title": "File analysis demo" # опционально - передача информация об источнике API-вызова
    },
    json={
        "model": "openai/gpt-4o-mini",
        "messages": [{"role": "system", "content": context_prompt},
                     {"role": "user", "content": question}]
    }
)

# Обработка ответа
response_data = response.json()
msg = response_data["choices"][0]["message"]["content"]

print("Ответ:", msg)

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!"
      }
    ]
  }'

Поддержка диалога

# Ход 1
messages = [
   {"role": "user", "content": "Кто такой Барак Обама?"}
]

# Получили ответ - "Барак Обама - президент США"
# добавляем его в массив с ролью assistant
# задаем еще вопрос - "Кто его жена?"

# Ход 2 - здесь запрос Кто его жена? будет обработан в контексте
messages = [
   {"role": "user", "content": "Кто такой Барак Обама?"},
   {"role": "assistant", "content": "Барак Обама - президент США"},
   {"role": "user", "content": "Кто его жена?"}
]

Генерация текста с Web search

• Описанию моделей Perplexity в Моделях
• Примеру клиента с поиском (Сервисы > Чат с веб поиском)
• Документации Perplexity – https://docs.perplexity.ai/api-reference/chat-completions

Получение размышлений в reasoning моделях (o1,R1)

"choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The numbers from 1 to 5 written sequentially are:  \n1, 2, 3, 4, 5.",
        "reasoning": "Okay, let's see. The user wants me to write the numbers from 1 to 5 in order. That sounds straightforward, but I should make sure I do it correctly. Let me start by recalling the sequence of numbers.\n\nFirst, 1 is the starting point. Then comes 2, followed by 3. After that, it's 4 and then 5. Wait, is there any chance I might mix up the order? I don't think so. Numbers from 1 to 5 are pretty basic. Let me count them again in my head to double-check: 1, 2, 3, 4, 5. Yep, that's five numbers, each increasing by one. \n\nHmm, maybe the user wants them listed each on a separate line or separated by commas. The instruction says \"sequentially,\" so probably just one after the other. The example didn't specify formatting, but to be clear, I should present them in a simple sequence. Let me write them out: 1, 2, 3, 4, 5. \n\nWait, but maybe they want each number written out as a word? Like one, two, three, four, five. The original query says \"numbers,\" which could be interpreted either way. But since it's about writing the numbers, not the words, digits are more likely expected. \n\nAlternatively, maybe they want a vertical list. But the example response the assistant is supposed to generate uses commas. Let me check the user's exact request again: \"Write the numbers from 1 to 5 sequentially.\" The key word is \"sequentially,\" which just means in order. So the simplest way is to list them in order separated by commas. \n\nI think that's all. No complications here. Just make sure not to skip any number or repeat any. Let me verify once more: starting at 1, each subsequent number increases by 1 until 5. So 1, then 2, then 3, then 4, then 5. No mistakes there. Alright, ready to present the answer."
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],

Получение ответа в виде JSON

1. Напишите промт, в котором явно указываете, что ожидаете в ответе JSON.
2. (Опционально) Добавьте указание response_format={ “type”: “json_output” } в запросе, некоторые поставщики учитывают это и стараются вернуть вам JSON.

math_tutor_prompt = '''
        You are a helpful math tutor. You will be provided with a math problem,
        and your goal will be to output an answer.
    '''

    prompt = "There are equation 'x+3=8'. Find the integer 'x'. Answer with ONLY JSON dictionary with final 'x', where 'x' is key of dictionary, and value of key is answer. "

    messages = []

    messages.append({"role": "system", "content": math_tutor_prompt})
    messages.append({"role": "user", "content": prompt})

    response = openai.ChatCompletion.create(
        headers={
            "X-Title": "Test (no-stream, json_output)"
        },
        model=model,
        messages=messages,
        temperature=0.01,
        max_tokens=4000,
        response_format={
            "type": "json_output"
        }
    )

Генерация 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"
)

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-модель (распознавание картинок, OCR) (текст+картинка -> текст)

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])

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)

Отправка нескольких изображений

messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Image 1"},
                {
                    "type": "image_url",
                    "image_url": f"data:image/jpeg;base64,{base64_image1}",
                },
            ],
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Image 2"},
                {
                    "type": "image_url",
                    "image_url": f"data:image/jpeg;base64,{base64_image2}",
                },
            ],
        },
        {
            "role": "user",
            "content": "Какая разница между этими двумя изображениями?"
        }
    ]

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

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"
  # aspect_ratio="1:1" 
  # ряд моделей, типа Imagen 4, требуют указания aspect_ratio вместо size. Смотрите карточку модели
)

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"
  }'

Github MCP Server for image generation

Редактирование изображения

import base64
import os
from pathlib import Path

import time

import requests

api_key = "your_vsegpt_key"

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


base64_image = encode_image("test_car.png")

# Create API session
session = requests.Session()

# Set up authorization headers
session.headers.update({
    "Content-Type": "application/json",
    "Authorization": f"Bearer {api_key}"
})

# VseGPT API endpoint for image generation
url = "https://api.vsegpt.ru/v1/images/generations"

# Prepare payload as specified
payload = {
    "model": "img2img-google/flash-edit",
    "prompt": "Make the car black",
    "response_format": "b64_json",
    "image_url": f"data:image/jpeg;base64,{base64_image}",
    # в случае нескольких изображений, например, для flash-edit-multi 
    # используйте также image2_url, image3_url, image4_url - вплоть до image10_url 
    # (смотрите возможности нейросети по числу входных изображений)
}
# Update headers with title
session.headers.update({"X-Title": f"Test Image-to-Image"})
# Make the API request
response = session.post(url, json=payload)
# Check if request was successful
if response.status_code == 200:
    # Saving image to file

    # Get base64 string from response
    response_json = response.json()
    print(response_json)
    b64_data = response_json["data"][0]["b64_json"]

    # Get the directory of the current script
    script_dir = os.path.dirname(os.path.abspath(__file__))

    # Create tmp_images directory in the same folder as the script
    tmp_dir = Path(script_dir) / "tmp_images"
    tmp_dir.mkdir(exist_ok=True)

    # Generate filename with timestamp
    timestamp = int(time.time())
    filename = f"{timestamp}.jpg"
    filepath = tmp_dir / filename

    # Decode base64 and save to file
    with open(filepath, "wb") as img_file:
        img_file.write(base64.b64decode(b64_data))

    # Return absolute path to the file
    # return str(filepath.absolute())
    print("File here: ",str(filepath.absolute()))
else:
    raise ValueError(f"{response.status_code}: {response.text}")

Альтернативный OpenAI-совместимый вариант через v1/images/edits

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

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="json",
  language="ru", # опционально, может быть пустым
  file=audio_file
)

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"
  -F response_format="json"

Генерация речи (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

Конвертация документов в текст (utils/extract-text)

import requests
import base64

# Кодируем файл в base64
with open("example.pdf", "rb") as file:
    encoded_file = base64.b64encode(file.read()).decode('utf-8')

# Отправляем запрос
response = requests.post(
    "https://api.vsegpt.ru/v1/extract_text",
    headers = {
        "Authorization": "Bearer VSEGPT_API_KEY", # ваш ключ vsegpt
        "X-Title": "Doc2Text example" # опционально
    },
    json={
        "encoded_base64_file": encoded_file,
        "filename": "example.pdf",
        "model": "utils/extract-text-1.0", # вариант - utils/pdf-ocr-1.0 для оптического распознавания OCR
        # "return_images": True, # для utils/pdf-ocr-1.0 также возвращает картинки в base64
    }
)

# print(response.text)

response.raise_for_status()

# Получаем результат
print(response.json()["text"])

Генерация видео (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}"

# Если модель поддерживает - добавляем в JSON запроса указание последнего фрейма видео
payload["end_image_url"] = f"data:image/jpeg;base64,{end_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)

С# (async)

static async Task Main()
        {

            string apiKey = "sk-or-vv-86*************"; // ваш ключ в VseGPT после регистрации
            string baseApiUrl = "https://api.vsegpt.ru/v1/";
            string prompt = "Напиши последовательно числа от 1 до 10";

            try
            {
                HttpClient client = new HttpClient();
                client.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");

                List<dynamic> messages = new List<dynamic>();
                messages.Add(new { role = "user", content = prompt });

                var requestData = new
                {
                    model = "openai/gpt-4o-mini",
                    messages = messages,
                    temperature = 0.7,
                    n = 1,
                    max_tokens = Convert.ToInt32(prompt.Length * 1.5),
                    extra_headers = new { X_Title = "My App" } // опционально - передача информации об источнике API-вызова
                };

                var jsonRequest = Newtonsoft.Json.JsonConvert.SerializeObject(requestData);
                var content = new StringContent(jsonRequest, Encoding.UTF8, "application/json");

                var response = await client.PostAsync(baseApiUrl + "chat/completions", content);

                if (response.IsSuccessStatusCode)
                {
                    var jsonResponse = await response.Content.ReadAsStringAsync();
                    dynamic responseData = Newtonsoft.Json.JsonConvert.DeserializeObject(jsonResponse);
                    string responseContent = responseData.choices[0].message.content;
                    Console.WriteLine("Response: " + responseContent);
                }
                else
                {
                    Console.WriteLine("Error: " + response.ReasonPhrase);
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception: " + ex.Message);
            }
}

TypeScript

fetch("https://api.vsegpt.ru/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${VSEGPT_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "openai/gpt-3.5-turbo",
    "messages": [
      {"role": "user", "content": "What is the meaning of life?"}
    ]
  })
});

TypeScript (OpenAI library)

import OpenAI from "openai"

const openai = new OpenAI({
  baseURL: "https://api.vsegpt.ru/v1",
  apiKey: $VSEGPT_API_KEY,
  // dangerouslyAllowBrowser: true,
})
async function main() {
  const completion = await openai.chat.completions.create({
    model: "openai/gpt-3.5-turbo",
    messages: [
      { role: "user", content: "Say this is a test" }
    ],
  })

  console.log(completion.choices[0].message)
}
main()

Библиотеки для других языков

https://platform.openai.com/docs/libraries/community-libraries

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

https://github.com/saintbyte/vsegpt_api