> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-d2fddb8a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Introducción
> Referencia de la API de Venice que cubre autenticación, depuración, compatibilidad con OpenAI, cabeceras de respuesta, gestión de errores y la lista completa de endpoints admitidos.
La API de Venice ofrece interfaces REST y de streaming basadas en HTTP para crear aplicaciones de IA con modelos sin censura e inferencia privada. Puedes crear con generación de texto, creación de imágenes, embeddings y más, todo ello sin políticas de contenido restrictivas. Hay ejemplos de integración y SDKs disponibles en la [documentación](/overview/getting-started). Nuestra referencia de la API también está disponible como [especificación OpenAPI YAML.](https://api.venice.ai/doc/api/swagger.yaml)
## Autenticación
La API de Venice usa API keys para la autenticación. Crea y gestiona tus API keys en tu [configuración de API](https://venice.ai/settings/api).
Todas las solicitudes a la API requieren autenticación HTTP Bearer:
```
Authorization: Bearer VENICE_API_KEY
```
Tu API key es un secreto. No la compartas ni la expongas en ningún código del lado del cliente.
## Compatibilidad con OpenAI
La API de Venice implementa la especificación de la API de OpenAI, lo que garantiza compatibilidad con clientes y herramientas existentes de OpenAI. Esto te permite integrarte con Venice usando la conocida interfaz de OpenAI mientras accedes a las funciones únicas y los modelos sin censura de Venice.
### Configuración
Configura tu cliente para usar la URL base de Venice (`https://api.venice.ai/api/v1`) y realiza tu primera solicitud:
```bash curl theme={null}
curl https://api.venice.ai/api/v1/chat/completions \
-H "Authorization: Bearer $VENICE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "venice-uncensored",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```javascript JavaScript theme={null}
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.VENICE_API_KEY,
baseURL: "https://api.venice.ai/api/v1",
});
const response = await client.chat.completions.create({
model: "venice-uncensored",
messages: [{ role: "user", content: "Hello!" }]
});
console.log(response.choices[0].message.content);
```
```python Python theme={null}
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ.get("VENICE_API_KEY"),
base_url="https://api.venice.ai/api/v1"
)
response = client.chat.completions.create(
model="venice-uncensored",
messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
```
## Funciones específicas de Venice
### System prompts
Venice proporciona system prompts predeterminados diseñados para garantizar respuestas naturales y sin censura del modelo. Tienes dos opciones para gestionar los system prompts:
1. **Comportamiento predeterminado**: tus system prompts se añaden a los predeterminados de Venice
2. **Comportamiento personalizado**: desactiva por completo los system prompts de Venice
#### Desactivar los system prompts de Venice
Usa la opción `venice_parameters` para eliminar los system prompts predeterminados de Venice:
```bash curl theme={null}
curl https://api.venice.ai/api/v1/chat/completions \
-H "Authorization: Bearer $VENICE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "venice-uncensored",
"messages": [
{"role": "system", "content": "Your custom system prompt"},
{"role": "user", "content": "Why is the sky blue?"}
],
"venice_parameters": {
"include_venice_system_prompt": false
}
}'
```
```javascript JavaScript theme={null}
const completion = await client.chat.completions.create({
model: "venice-uncensored",
messages: [
{
role: "system",
content: "Your custom system prompt",
},
{
role: "user",
content: "Why is the sky blue?",
},
],
venice_parameters: {
include_venice_system_prompt: false,
},
});
```
```python Python theme={null}
response = client.chat.completions.create(
model="venice-uncensored",
messages=[
{"role": "system", "content": "Your custom system prompt"},
{"role": "user", "content": "Why is the sky blue?"}
],
extra_body={
"venice_parameters": {
"include_venice_system_prompt": False
}
}
)
```
### Venice Parameters
El objeto `venice_parameters` te permite acceder a funciones específicas de Venice no disponibles en la API estándar de OpenAI:
| Parámetro | Tipo | Descripción | Predeterminado |
| ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| `character_slug` | string | El slug del personaje de un personaje público de Venice (visible como "Public ID" en la página del personaje publicado) | - |
| `strip_thinking_response` | boolean | Elimina los bloques `` de la respuesta (modelos que usan el formato heredado de etiqueta ``). Consulta [Modelos de razonamiento](/guides/features/reasoning-models). | `false` |
| `disable_thinking` | boolean | En modelos de razonamiento compatibles, desactiva el pensamiento y elimina los bloques `` de la respuesta | `false` |
| `enable_web_search` | string | Activa la búsqueda web para esta solicitud (`off`, `on`, `auto`: auto activa según el criterio del modelo)
Se aplican precios adicionales por uso, consulta [precios](/overview/pricing#web-search-and-scraping). | `off` |
| `enable_web_scraping` | boolean | Activa el scraping web de hasta 5 URLs detectadas en el mensaje del usuario. El contenido raspado complementa las respuestas y omite la búsqueda web. Solo se facturan las URLs raspadas con éxito.
Se aplican precios adicionales por uso, consulta [precios](/overview/pricing#web-search-and-scraping). | `false` |
| `enable_x_search` | boolean | Activa la búsqueda nativa de xAI (web + X/Twitter) para los modelos Grok compatibles (p. ej., `grok-4-20-beta`). Ofrece resultados de búsqueda de mayor calidad utilizando la infraestructura de búsqueda de xAI. Cuando está activada, se omite la búsqueda web estándar de Venice.
Se aplican precios adicionales por uso, consulta [precios](/overview/pricing#web-search-and-scraping). | `false` |
| `enable_web_citations` | boolean | Cuando la búsqueda web está activada, solicita al LLM que cite sus fuentes utilizando el formato `[REF]0[/REF]` | `false` |
| `include_search_results_in_stream` | boolean | Experimental: incluye los resultados de búsqueda en el stream como primer chunk emitido | `false` |
| `return_search_results_as_documents` | boolean | Expone los resultados de búsqueda en una tool call compatible con OpenAI llamada `venice_web_search_documents` para la integración con LangChain | `false` |
| `include_venice_system_prompt` | boolean | Si se deben incluir los system prompts predeterminados de Venice junto con los system prompts especificados | `true` |
Estos parámetros también se pueden especificar como sufijos de modelo añadidos al nombre del modelo (p. ej., `zai-org-glm-5:enable_web_search=auto`). Consulta [Sufijos de características del modelo](/api-reference/endpoint/chat/model_feature_suffix) para más detalles.
### Prompt caching
Venice admite prompt caching en modelos seleccionados para reducir la latencia y los costes en contenido repetido. Para los modelos compatibles, Venice almacena automáticamente en caché los system prompts: no se requieren cambios de código. También puedes marcar manualmente contenido para caching usando la propiedad `cache_control` en el contenido del mensaje.
| Parámetro | Tipo | Descripción |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt_cache_key` | string | Indicación opcional de enrutamiento para mejorar las tasas de aciertos de caché. Cuando se proporciona, Venice enruta las solicitudes a la misma infraestructura backend, aumentando la probabilidad de aciertos de caché a lo largo de conversaciones multi-turno. |
Consulta [Prompt caching](/guides/features/prompt-caching) para detalles sobre cómo funciona el caching, la facturación y las mejores prácticas.
## Referencia de cabeceras de respuesta
Todas las respuestas de la API de Venice incluyen cabeceras HTTP que proporcionan metadatos sobre la solicitud, los límites de velocidad, la información del modelo y el saldo de la cuenta. Además de los códigos de error devueltos por las respuestas de la API, puedes inspeccionar estas cabeceras para obtener el ID único de una solicitud concreta a la API, monitorizar los límites de velocidad y hacer seguimiento del saldo de tu cuenta.
Venice recomienda registrar los IDs de solicitud (cabecera `CF-RAY`) en despliegues de producción para una resolución de problemas más eficiente con nuestro equipo de soporte, si fuera necesario.
La tabla siguiente ofrece una referencia completa de todas las cabeceras que puedes encontrar:
| Cabecera | Tipo | Propósito | Cuándo se devuelve |
| ------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **Cabeceras HTTP estándar** | | | |
| `Content-Type` | string | Tipo MIME del cuerpo de la respuesta (`application/json`, `text/csv`, `image/png`, etc.) | Siempre |
| `Content-Encoding` | string | Codificación usada para comprimir el cuerpo de la respuesta (`gzip`, `br`) | Cuando el cliente envía la cabecera `Accept-Encoding` |
| `Content-Disposition` | string | Cómo debe mostrarse el contenido (p. ej., `attachment; filename=export.csv`) | Al descargar archivos o exportaciones |
| `Date` | string | Marca de tiempo en formato RFC 7231 cuando se generó la respuesta | Siempre |
| **Identificación de la solicitud** | | | |
| `CF-RAY` | string | Identificador único de esta solicitud a la API, utilizado para resolución de problemas y solicitudes de soporte | Siempre |
| `x-venice-version` | string | Versión/revisión actual del servicio de la API de Venice (p. ej., `20250828.222653`) | Siempre |
| `x-venice-timestamp` | string | Marca de tiempo del servidor cuando se procesó la solicitud (formato ISO 8601) | Cuando el seguimiento de marca de tiempo está activado |
| `x-venice-host-name` | string | Hostname del servidor que procesó la solicitud | Respuestas de error y escenarios de depuración |
| **Información del modelo** | | | |
| `x-venice-model-id` | string | Identificador único del modelo de IA usado para la solicitud (p. ej., `venice-01-lite`) | Endpoints de inferencia que usan modelos de IA |
| `x-venice-model-name` | string | Nombre amigable/de visualización del modelo de IA usado (p. ej., `Venice Lite`) | Endpoints de inferencia que usan modelos de IA |
| `x-venice-model-router` | string | Servicio router/backend que manejó la inferencia del modelo | Endpoints de inferencia cuando hay información de enrutamiento disponible |
| `x-venice-model-deprecation-warning` | string | Mensaje de aviso para modelos programados para deprecación | Al usar un modelo deprecado |
| `x-venice-model-deprecation-date` | string | Fecha en la que el modelo será deprecado (fecha ISO 8601) | Al usar un modelo deprecado |
| **Información de límites de velocidad** | | | |
| `x-ratelimit-limit-requests` | number | Número máximo de solicitudes permitidas en la ventana de tiempo actual | Todas las solicitudes autenticadas |
| `x-ratelimit-remaining-requests` | number | Número de solicitudes restantes en la ventana de tiempo actual | Todas las solicitudes autenticadas |
| `x-ratelimit-reset-requests` | number | Marca de tiempo Unix cuando se restablece el límite de velocidad de solicitudes | Todas las solicitudes autenticadas |
| `x-ratelimit-limit-tokens` | number | Número máximo de tokens (prompt + completion) permitidos en la ventana de tiempo | Todas las solicitudes autenticadas |
| `x-ratelimit-remaining-tokens` | number | Número de tokens restantes en la ventana de tiempo actual | Todas las solicitudes autenticadas |
| `x-ratelimit-reset-tokens` | number | Duración en segundos hasta que se restablece el límite de velocidad de tokens | Todas las solicitudes autenticadas |
| `x-ratelimit-type` | string | Tipo de límite de velocidad aplicado (`user`, `api_key`, `global`) | Cuando se aplica un límite de velocidad |
| **Cabeceras de paginación** | | | |
| `x-pagination-limit` | number | Número de elementos por página | Endpoints paginados |
| `x-pagination-page` | number | Número de página actual (basado en 1) | Endpoints paginados |
| `x-pagination-total` | number | Número total de elementos en todas las páginas | Endpoints paginados |
| `x-pagination-total-pages` | number | Número total de páginas | Endpoints paginados |
| **Información del saldo de la cuenta** | | | |
| `x-venice-balance-diem` | string | Tu saldo de tokens DIEM antes de procesar la solicitud | Todas las solicitudes autenticadas |
| `x-venice-balance-usd` | string | Tu saldo de crédito en USD antes de procesar la solicitud | Todas las solicitudes autenticadas |
| **Cabeceras de seguridad de contenido** | | | |
| `x-venice-is-blurred` | string | Indica si la imagen generada fue difuminada debido a las políticas de contenido (`true`/`false`) | Generación de imágenes con Safe Venice activado |
| `x-venice-is-content-violation` | string | Indica si el contenido infringe las políticas de contenido de Venice (`true`/`false`) | Endpoints de generación de contenido |
| `x-venice-is-adult-model-content-violation` | string | Indica si el contenido infringe las políticas de contenido para modelos para adultos (`true`/`false`) | Endpoints de generación de imágenes |
| `x-venice-contains-minor` | string | Indica si la imagen contiene menores (`true`/`false`) | Endpoints de análisis de imágenes con detección de edad |
| **Información del cliente** | | | |
| `x-venice-middleface-version` | string | Versión del cliente middleface de Venice | Solicitudes desde clientes middleface de Venice |
| `x-venice-mobile-version` | string | Versión del cliente de la app móvil de Venice | Solicitudes desde aplicaciones móviles |
| `x-venice-request-timestamp-ms` | number | Marca de tiempo de la solicitud proporcionada por el cliente en milisegundos | Cuando el cliente proporciona marca de tiempo en la solicitud |
| `x-venice-control-instance` | string | Identificador de instancia de control para depuración | Endpoints de generación de imágenes para depuración |
| **Cabeceras de autenticación** | | | |
| `x-auth-refreshed` | string | Indica si el token de autenticación se refrescó durante la solicitud (`true`/`false`) | Cuando los tokens de autenticación se auto-refrescan |
| `x-retry-count` | number | Número de intentos de reintento para la solicitud | Cuando se producen reintentos de la solicitud |
### Notas importantes
* **Mayúsculas/minúsculas en nombres de cabeceras**: las cabeceras HTTP no distinguen entre mayúsculas y minúsculas, pero Venice utiliza minúsculas con guiones para coherencia
* **Valores de cadena**: los valores booleanos en las cabeceras se devuelven como cadenas (`"true"` o `"false"`)
* **Valores numéricos**: los números grandes y los valores de saldo pueden devolverse como cadenas para evitar pérdida de precisión
* **Cabeceras opcionales**: no todas las cabeceras se devuelven en cada respuesta; su presencia depende del endpoint y del contexto de la solicitud
* **Compresión**: utiliza `Accept-Encoding: gzip, br` en las solicitudes para recibir respuestas comprimidas donde se admita
### Ejemplo: acceder a las cabeceras de respuesta
```javascript theme={null}
// Tras hacer una solicitud a la API, accede a las cabeceras desde el objeto de respuesta
const requestId = response.headers.get('CF-RAY');
const remainingRequests = response.headers.get('x-ratelimit-remaining-requests');
const remainingTokens = response.headers.get('x-ratelimit-remaining-tokens');
const usdBalance = response.headers.get('x-venice-balance-usd');
// Comprobar avisos de deprecación de modelos
const deprecationWarning = response.headers.get('x-venice-model-deprecation-warning');
if (deprecationWarning) {
console.warn(`Model Deprecation: ${deprecationWarning}`);
}
```
## Mejores prácticas
1. **Límites de velocidad**: monitoriza las cabeceras `x-ratelimit-remaining-requests` y `x-ratelimit-remaining-tokens` e implementa backoff exponencial
2. **Monitorización del saldo**: rastrea las cabeceras `x-venice-balance-usd` y `x-venice-balance-diem` para evitar interrupciones del servicio
3. **System prompts**: prueba con y sin los system prompts de Venice para encontrar el mejor ajuste para tu caso de uso
4. **API keys**: mantén tus API keys seguras y rótalas regularmente
5. **Registro de solicitudes**: registra los valores de la cabecera `CF-RAY` para la resolución de problemas con soporte
6. **Deprecación de modelos**: comprueba las cabeceras `x-venice-model-deprecation-warning` al usar modelos
## Diferencias con la API de OpenAI
Aunque Venice mantiene una alta compatibilidad con la especificación de la API de OpenAI, hay algunas diferencias clave:
1. **venice\_parameters**: configuraciones adicionales como `enable_web_search`, `character_slug` y `strip_thinking_response` para funcionalidad ampliada
2. **System prompts**: Venice añade tus system prompts a los predeterminados que optimizan respuestas sin censura (desactívalo con `include_venice_system_prompt: false`)
3. **Ecosistema de modelos**: Venice ofrece su propia [línea de modelos](/overview/models) incluyendo modelos sin censura y de razonamiento; usa los IDs de modelo de Venice en lugar de los mapeos de OpenAI
4. **Cabeceras de respuesta**: cabeceras únicas para el seguimiento de saldo (`x-venice-balance-usd`, `x-venice-balance-diem`), avisos de deprecación de modelos y flags de seguridad de contenido
5. **Políticas de contenido**: políticas más permisivas con modelos sin censura dedicados y filtrado de contenido opcional
## Estabilidad de la API
Venice mantiene la compatibilidad hacia atrás para los endpoints y parámetros v1. Para la política del ciclo de vida de los modelos, avisos de deprecación y orientación de migración, consulta [Deprecaciones](/overview/deprecations).
## Especificación OpenAPI y datos en bruto
Para acceso programático a los documentos y datos de la API de Venice — incluido el uso con RAG (Retrieval-Augmented Generation) — están disponibles los siguientes recursos:
* [Especificación OpenAPI (YAML)](https://api.venice.ai/doc/api/swagger.yaml) — la especificación completa de la API en formato YAML
* [Código fuente de los docs](https://github.com/veniceai/api-docs/archive/refs/heads/main.zip) — todas las páginas de documentación (formato `.mdx`) como archivo descargable
***
Los campos de solicitud no listados en esta documentación pueden ser aceptados pero no se validan ni se garantiza que funcionen.