Альтернатива Venice API на Python: настройка OpenAI SDK
Вы можете использовать официальный Python SDK OpenAI для этого API, изменив базовый URL, ключ и имя модели. Ниже приведен рабочий код для каждой распространенной задачи.

Ключевые моменты
- Установите пакет openai, установите base_url в https://api.veniceapialternative.com/v1 и модель в uncensored.
- Потоковая передача, вызов инструментов и JSON-режим работают через стандартные вызовы SDK.
- Держите параллельную работу на уровне не более 8 одновременных запросов для полного ключа (2 для пробного ключа).
- 429 означает rate_limited, concurrency или временную перегрузку; сделайте паузу и повторите попытку.
Установка и первый вызов
Для настройки альтернативы Venice API на Python вам не нужна специальная библиотека. Сервис использует формат чата OpenAI, поэтому стандартный SDK работает. Установите его с помощью pip install openai, затем получите ключ. Новые пользователи могут получить $0.50 пробного баланса на странице API-ключ после регистрации через Google или с помощью электронной почты и пароля. Карта не требуется.
Храните ключ в переменной окружения, а не в файле исходного кода. Затем создайте клиент с базовым URL и вызовите модель uncensored:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "You are a concise writing assistant."},
{"role": "user", "content": "Give me three opening lines for a noir story."},
],
temperature=0.8,
)
print(resp.choices[0].message.content)
print(resp.usage)
SDK отправляет заголовок Authorization: Bearer <key> за вас. Объект usage показывает токены промпта и завершения, которые вы будете использовать для отслеживания затрат позже. Если вызов завершится ошибкой аутентификации, проверьте, что ключ не содержит завершающий символ новой строки и что базовый URL заканчивается на /v1.
Параметры temperature, top_p, stop и seed, а также штрафы за частоту и присутствие передаются модели, поэтому вы можете настраивать сэмплирование так же, как и в других местах. Не указывайте max_tokens, если хотите, чтобы модель использовала оставшееся место в окне, или установите его, если хотите жесткий предел длины ответа и стоимости.
Проверка подключения через эндпоинт моделей
Прежде чем что-либо создавать, убедитесь, что эндпоинт доступен. Второй поддерживаемый метод, GET /v1/models, перечисляет то, что может использовать ключ:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
for m in client.models.list():
print(m.id, m.id == "uncensored")
Вы должны увидеть uncensored. Это единственный идентификатор модели, и его нужно передавать как model в каждом запросе. Если вы переносите приложение, которое выбирает между несколькими именами моделей, замените логику выбора на константу. Выбирать больше не из чего.
Полная справочная информация по параметрам находится на странице документации. Поддерживается только текстовый чат: нет изображений, аудио, эмбеддингов или дообучения, поэтому удалите эти вызовы из любого кода, который вы переносите.
Потоковые ответы
Потоковая передача возвращает токены по мере их генерации, что делает интерфейсы чата более отзывчивыми. Установите stream=True и итерируйте по фрагментам. Данные об использовании поступают в конце потока, поэтому проверяйте фрагменты, которые не содержат вариантов ответа:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Describe a rainy harbor town in 120 words."}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if getattr(chunk, "usage", None):
print("\n", chunk.usage)
Одна деталь важна для планирования мощности: потоковый запрос удерживает слот параллельности до конца потока. Если пользователь открывает поток и уходит, не закрывая его, этот слот остается занятым. Закрывайте потоки на стороне клиента, когда пользователь уходит, и устанавливайте тайм-аут запроса.
Вызов инструментов и JSON-режим
Вызов инструментов следует формату OpenAI. Вы описываете функции в tools, модель возвращает tool_calls, вы выполняете функцию и отправляете результат обратно с role: "tool":
import json
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
tools = [{
"type": "function",
"function": {
"name": "roll_dice",
"description": "Roll a die with the given number of sides",
"parameters": {
"type": "object",
"properties": {"sides": {"type": "integer"}},
"required": ["sides"],
},
},
}]
messages = [{"role": "user", "content": "Roll a twenty-sided die for the next encounter."}]
first = client.chat.completions.create(
model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)
msg = first.choices[0].message
if msg.tool_calls:
call = msg.tool_calls[0]
args = json.loads(call.function.arguments)
result = {"value": 14, "sides": args["sides"]}
messages.append(msg)
messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)
Всегда парсите function.arguments с помощью try/except в продакшн-коде, так как модель иногда может выдать некорректный JSON. JSON-режим помогает, когда вам нужен структурированный вывод без инструментов:
import json
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
r = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Reply with a JSON object with keys name, mood and hook."},
{"role": "user", "content": "Invent a tavern keeper for a fantasy campaign."},
],
)
print(json.loads(r.choices[0].message.content))
Укажите модели в промпте, какие ключи вы хотите. JSON-режим делает вывод действительным JSON, но он не может угадать вашу схему.
Обработка ошибок 429 и лимитов запросов
Полный ключ позволяет 8 одновременных запросов и 300 запросов в минуту. Пробный ключ позволяет 2 одновременных и 60 в минуту. При превышении лимита вы получаете HTTP 429, а код ошибки указывает, какой именно:
rate_limited: слишком много запросов в минуту. Замедлите темп.concurrency: слишком много запросов в обработке. Дождитесь завершения некоторых.- 429 с заголовком
Retry-After: 5: временная перегрузка. Подождите 5 секунд и повторите попытку.
SDK по умолчанию уже выполняет несколько повторных попыток и учитывает Retry-After. Для более сложных случаев добавьте собственную обёртку и читайте заголовки лимитов. Вы можете получить доступ к сырому ответу через with_raw_response:
import os
import time
import openai
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
max_retries=0,
)
def ask(prompt, attempts=4):
for n in range(attempts):
try:
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
)
print("balance:", raw.headers.get("X-Balance-USD"),
"request id:", raw.headers.get("X-Request-Id"))
return raw.parse().choices[0].message.content
except openai.RateLimitError as e:
wait = int(e.response.headers.get("Retry-After", 2 ** n))
time.sleep(wait)
raise RuntimeError("still rate limited after retries")
print(ask("Name three plot twists for a heist story."))
Логируйте X-Request-Id при каждой ошибке. Если вы свяжетесь с поддержкой, этот ID позволит им найти точный вызов. Заголовок X-Balance-USD дает вам оставшийся баланс без дополнительного запроса. Ошибочные и отклоненные запросы не оплачиваются.
Выполнение запросов параллельно без достижения предела
Для пакетных задач используйте асинхронный клиент и семафор, размер которого соответствует вашему ключу. Для полного ключа потолок составляет 8. Оставьте небольшой запас, если вы также обслуживаете живых пользователей с того же ключа.
import asyncio
import os
from openai import AsyncOpenAI
client = AsyncOpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
gate = asyncio.Semaphore(6)
async def summarize(text):
async with gate:
r = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Summarize in one sentence: " + text}],
max_tokens=80,
)
return r.choices[0].message.content
async def main():
docs = ["First long text ...", "Second long text ...", "Third long text ..."]
for line in await asyncio.gather(*(summarize(d) for d in docs)):
print(line)
asyncio.run(main())
Темп имеет значение и для лимита в минуту. При 6 параллельных воркерах и 4 секундах на вызов вы отправляете около 90 запросов в минуту, что значительно ниже 300. Если ваши вызовы быстрые, добавьте небольшой sleep или token bucket, чтобы не превысить предел в виде всплесков.
Перенос существующего проекта Python
Большинство миграций проще, чем ожидают. Если ваш код уже создает клиент OpenAI(...), вы изменяете два аргумента конструктора и одну строку. Если вы читаете настройки из переменных окружения, часто можно вообще не трогать код: пакет openai читает OPENAI_API_KEY и OPENAI_BASE_URL, поэтому установка этих двух переменных в вашей оболочке или в файле .env направляет всю программу на новый эндпоинт.
Затем найдите в проекте эти элементы, так как они являются обычными источниками поломок:
- Жестко заданные имена моделей. Замените все старые имена на
uncensored. Поиск поmodel=находит большинство из них. - Вызовы других эндпоинтов. Вызовы изображений, аудио, эмбеддингов и дообучения здесь не имеют аналогов. Направьте их в сервис, который их предоставляет, или удалите.
- Специфичные для поставщика дополнения. Дополнительные поля запроса или пользовательские заголовки, принадлежащие вашему старому провайдеру, могут вызвать ошибки. Удалите их до формата OpenAI.
- Бюджеты токенов. Окно составляет 100 000 токенов для промпта и генерации. Если вы сокращали историю, чтобы она поместилась в меньшее окно, теперь вы можете хранить больше, но следите за стоимостью, потому что каждое удерживаемое сообщение оплачивается заново на каждом шаге.
Промпты заслуживают повторного тестирования. Системный промпт, который работал для одной модели, может дать другой тон на другой, поэтому запустите свои десять самых важных промптов и сравните вывод с тем, что вы ожидаете, перед релизом.
Распространенные проблемы и их решения
Краткий список ошибок, которые чаще всего возникают, когда люди подключают новый API, совместимый с OpenAI, из Python:
- Ошибка 404 при первом вызове. Базовый URL не содержит
/v1или имеет лишний сегмент пути. Он должен быть точноhttps://api.veniceapialternative.com/v1. - Ошибка 401 или аутентификации. Ключ неверен, содержит кавычки от скопированной строки
.envили не экспортирован в оболочку, запускающую Python. - Зависание запроса при больших входных данных. Максимальный размер тела — 8 МБ. Вставка огромного файла в промпт может превысить лимит до достижения лимита токенов. Разделите текст.
- Случайные ошибки 429 во время тестирования. На пробном ключе у вас только 2 параллельных запроса. Тестовый раннер, который запускает пять одновременно, превысит лимит. Запускайте тесты последовательно или пополните баланс и используйте полный ключ.
- Усечённые ответы. Проверьте
finish_reason. Значениеlengthозначает, что вывод достиг настройкиmax_tokensили заполнил окно. - Разные результаты при каждом запуске. Передайте
seedи низкийtemperature, если нужен воспроизводимый вывод для тестов.
Если что-то всё ещё выглядит неправильно, отправьте значение X-Request-Id в поддержку вместе со временем вызова.
Оценка стоимости в коде
Цена составляет $0.15 за 1M входных токенов и $0.50 за 1M выходных токенов. Небольшой помощник превращает любой блок использования в доллары:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.veniceapialternative.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
def cost_usd(usage):
return (usage.prompt_tokens * 0.15 + usage.completion_tokens * 0.50) / 1_000_000
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a limerick about a lighthouse."}],
)
print(round(cost_usd(r.usage), 6))
Запрос с 2 000 токенов промпта и 500 токенами генерации возвращает 0,00055. Запустите 1 000 таких запросов, и вы потратите $0,55. Пробный баланс в $0,50 покрывает около 909 таких запросов. После окончания пробного периода пополнения начинаются от $20, а кредит не сгорает; на странице цен указаны бонусные уровни. Если ваше приложение происходит из проекта чат-бота со своими подводными камнями, статья о распространённых ошибках API разбирает несколько из них, которые актуальны и здесь.
Дополнительные руководства
Вопросы и ответы
Какой пакет Python нужен?
Официальный пакет openai. Установите его с помощью pip, установите base_url в https://api.veniceapialternative.com/v1, и используйте модель uncensored. Другие клиентские библиотеки не нужны.
Работает ли потоковая передача с SDK?
Да. Передайте stream=True и итерируйте по чанкам. Информация об использовании доступна в конце потока.
Почему возникает ошибка 429?
Либо вы превысили лимит запросов в минуту (rate_limited), либо у вас было слишком много открытых запросов одновременно (concurrency), либо сервис был временно перегружен и вернул Retry-After: 5. Сделайте паузу и повторите запрос.
Сколько параллельных запросов я могу запустить?
Полный ключ позволяет 8 одновременных запросов и 300 в минуту. Пробный ключ позволяет 2 одновременных и 60 в минуту.
Могу ли я использовать LangChain или другие инструменты, совместимые с OpenAI?
Любой клиент, позволяющий установить базовый URL и ключ, совместимые с OpenAI, должен работать. Используйте тот же базовый URL и имя модели uncensored.