Alternativa a la API de Venice en Python: configuración del SDK de OpenAI
Puedes usar el SDK de Python oficial de OpenAI contra esta API cambiando la base URL, la clave y el nombre del modelo. A continuación hay código funcional para cada tarea común.

Puntos clave
- Instala el paquete openai, establece base_url en https://api.veniceapialternative.com/v1 y el modelo en uncensored.
- El streaming, las llamadas a herramientas y el modo JSON funcionan a través de las llamadas estándar del SDK.
- Mantén el trabajo paralelo en o por debajo de 8 peticiones simultáneas con una clave completa (2 en la clave de prueba).
- Un 429 significa rate_limited, concurrency o sobrecarga temporal; reduce la velocidad y reintenta.
Instala y haz la primera llamada
Para una alternativa a la API de Venice en Python, no necesitas una biblioteca especial. El servicio usa el formato de chat de OpenAI, por lo que el SDK estándar funciona. Instálalo con pip install openai, luego obtén una clave. Los nuevos usuarios pueden reclamar $0.50 de crédito de prueba en la página de clave de API después de registrarse con Google o con correo electrónico y contraseña. No se necesita tarjeta.
Almacena la clave en una variable de entorno en lugar de en tu archivo de código fuente. Luego crea un cliente con la URL base y llama al modelo 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)
El SDK envía Authorization: Bearer <key> por ti. El objeto usage muestra los tokens de prompt y completion, que usarás para el seguimiento de costos más tarde. Si la llamada falla con un error de autenticación, verifica que la clave no tenga un salto de línea al final y que la URL base termine en /v1.
Los parámetros temperature, top_p, stop y seed, más las penalizaciones de frecuencia y presencia, se pasan al modelo, por lo que puedes ajustar el muestreo de la misma manera que harías en otro lugar. Deja max_tokens fuera si quieres que el modelo use todo el espacio restante en la ventana, o establécelo cuando quieras un límite estricto en la longitud de la respuesta y el costo.
Verifica la conexión con el endpoint de modelos
Antes de construir cualquier cosa, confirma que el endpoint sea accesible. El segundo método soportado, GET /v1/models, lista lo que la clave puede usar:
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")
Deberías ver uncensored. Ese es el único ID de modelo, y es el valor para pasar como model en cada petición. Si estás migrando una aplicación que seleccionaba entre varios nombres de modelo, reemplaza la lógica de selección con una constante. No hay nada más que elegir.
La referencia completa de parámetros está en la página de documentación. Solo se soporta chat de texto: sin imágenes, audio, embeddings ni ajuste fino, así que elimina esas llamadas de cualquier código que traigas.
Respuestas en streaming
El streaming devuelve tokens a medida que se producen, lo que hace que las interfaces de chat se sientan más rápidas. Establece stream=True e itera sobre los fragmentos. El uso llega al final del streaming, así que protege los fragmentos que no contienen opciones:
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)
Un detalle importante para la planificación de capacidad: una petición en streaming ocupa su ranura de concurrencia hasta que termina el streaming. Si un usuario abre un streaming y se va sin cerrarlo, esa ranura permanece ocupada. Cierra los streaming en el lado del cliente cuando el usuario se vaya y establece un tiempo de espera de petición.
Llamadas a herramientas y modo JSON
Las llamadas a funciones siguen la estructura de OpenAI. Describes funciones en tools, el modelo devuelve tool_calls, ejecutas la función y envías el resultado de vuelta con 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)
Analiza siempre function.arguments con un try/except en código de producción, ya que un modelo puede emitir JSON mal formado de vez en cuando. El modo JSON ayuda cuando quieres salida estructurada sin llamadas a funciones:
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))
Indica al modelo en el prompt qué claves deseas. El modo JSON hace que la salida sea JSON válido, pero no puede adivinar tu esquema.
Manejo de errores 429 y límites de peticiones
Una clave completa permite 8 peticiones simultáneas y 300 peticiones por minuto. Una clave de prueba permite 2 simultáneas y 60 por minuto. Al superar un límite, obtienes un HTTP 429, y el código de error indica cuál:
rate_limited: demasiadas peticiones por minuto. Ralentiza.concurrency: demasiadas peticiones en vuelo. Espera a que algunas terminen.- Un 429 con un encabezado
Retry-After: 5: sobrecarga temporal. Espera 5 segundos y reintenta.
El SDK ya reintenta algunas veces por defecto y respeta Retry-After. Para algo más pesado, añade tu propio envoltorio y lee los encabezados de límite. Puedes acceder a la respuesta cruda a través de 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."))
Registra X-Request-Id con cada fallo. Si contactas a soporte, ese identificador les permite localizar la llamada exacta. El encabezado X-Balance-USD te muestra el crédito restante sin necesidad de otra petición. Las llamadas fallidas y rechazadas no se cobran.
Ejecución de peticiones en paralelo sin superar el límite
Para trabajos por lotes, usa el cliente asíncrono y un semáforo dimensionado a tu clave. Con una clave completa, 8 es el techo. Deja un poco de margen si también sirves usuarios en tiempo real desde la misma clave.
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())
El ritmo importa para el límite por minuto también. Con 6 trabajadores paralelos y 4 segundos por llamada, envías unas 90 solicitudes por minuto, muy por debajo de 300. Si tus llamadas son rápidas, añade una pequeña pausa o un cubo de tokens para no exceder el límite en ráfagas.
Migración de un proyecto Python existente
La mayoría de las migraciones son más pequeñas de lo que la gente espera. Si tu código ya crea un cliente OpenAI(...), cambias dos argumentos del constructor y una cadena. Si lees la configuración desde variables de entorno, a menudo puedes evitar tocar el código en absoluto: el paquete openai lee OPENAI_API_KEY y OPENAI_BASE_URL, así que establecer esas dos en tu shell o en tu archivo .env apunta todo el programa al nuevo endpoint.
Luego busca en tu proyecto estos elementos, porque son las fuentes habituales de rotura:
- Nombres de modelo codificados en duro. Reemplaza cada nombre antiguo con
uncensored. Un grep pormodel=encuentra la mayoría de ellos. - Llamadas a otros endpoints. Las llamadas de imagen, audio, embedding y ajuste fino no tienen equivalente aquí. Enrútalas a un servicio que las ofrezca, o elimínalas.
- Extras específicos del proveedor. Los campos de petición adicionales o los encabezados personalizados que pertenecen a tu antiguo proveedor pueden causar errores. Elimínalos para dejar el formato simple de OpenAI.
- Presupuestos de tokens. La ventana es de 100.000 tokens para el prompt más la generación. Si recortaste el historial para ajustarlo a una ventana más pequeña, ahora puedes mantener más, pero vigila el costo, porque cada mensaje mantenido se paga de nuevo en cada turno.
Los prompts merecen una nueva prueba. Un prompt de sistema que funcionó para un modelo puede dar un tono diferente en otro, así que ejecuta tus diez prompts más importantes y compara la salida con lo que esperas antes de lanzar.
Problemas comunes y sus correcciones
Una lista corta de los errores que aparecen más a menudo cuando la gente conecta un nuevo endpoint compatible con OpenAI desde Python:
- 404 en la primera llamada. La URL base no incluye
/v1, o tiene un segmento de ruta adicional. Debe ser exactamentehttps://api.veniceapialternative.com/v1. - 401 o error de autenticación. La clave es incorrecta, aún tiene comillas alrededor de una línea copiada de
.env, o nunca se exportó al shell que ejecuta Python. - La solicitud se cuelga con entradas grandes. El cuerpo máximo es de 8 MB. Pegar un archivo enorme en un prompt puede excederlo mucho antes de alcanzar el límite de tokens. Divide el texto.
- 429 aleatorios durante las pruebas. Con la clave de prueba solo tienes 2 solicitudes simultáneas. Un ejecutor de pruebas que lance cinco a la vez activará el límite. Ejecuta las pruebas en serie, o recarga y usa una clave completa.
- Respuestas truncadas. Verifica
finish_reason. Un valor delengthsignifica que la salida alcanzó tu configuración demax_tokenso llenó la ventana. - Resultados diferentes de ejecución a ejecución. Pasa
seedy untemperaturebajo si necesitas salida repetible para pruebas.
Si algo sigue pareciendo incorrecto, envía el valor X-Request-Id a soporte junto con la hora de la llamada.
Estimación de costos en código
El precio es $0,15 por 1M de tokens de entrada y $0,50 por 1M de tokens de salida. Un pequeño ayudante convierte cualquier bloque de uso en dólares:
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))
Una llamada con 2.000 tokens de prompt y 500 tokens de generación devuelve 0,00055 $. Ejecuta 1.000 de ellas y gastarás $0,55. El crédito de prueba de $0,50 cubre aproximadamente 909 llamadas de este tipo. Tras la prueba, las recargas comienzan en $20 y el crédito no caduca; la página de precios enumera las categorías de bonificación. Si tu aplicación proviene de un proyecto de chatbot con sus propios riesgos, el artículo sobre errores comunes de API aborda varios que también aplican aquí.
Más guías
Preguntas y respuestas
¿Qué paquete de Python necesito?
El paquete oficial openai. Instálalo con pip, establece base_url en https://api.veniceapialternative.com/v1 y usa el modelo uncensored. No se requiere otra biblioteca de cliente.
¿Funciona el streaming con el SDK?
Sí. Pasa stream=True e itera sobre los fragmentos. El uso se informa al final del streaming.
¿Por qué obtengo un error 429?
O bien superaste el límite de solicitudes por minuto (rate_limited), tenías demasiadas solicitudes abiertas a la vez (concurrency) o el servicio estaba brevemente sobrecargado y envió Retry-After: 5. Reduce la frecuencia y reintenta.
¿Cuántas peticiones simultáneas puedo ejecutar?
Una clave completa permite 8 solicitudes concurrentes y 300 por minuto. Una clave de prueba permite 2 concurrentes y 60 por minuto.
¿Puedo usar LangChain u otras herramientas compatibles con OpenAI?
Cualquier cliente que te permita configurar una Base URL y una clave compatibles con OpenAI debería funcionar. Usa la misma Base URL y el nombre del modelo uncensored.