> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-6ce01df5.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Introdução
> Documentação de referência da API Venice
A API Venice oferece interfaces REST baseadas em HTTP e streaming para criar aplicações de IA com modelos sem censura e inferência privada. Você pode criar com geração de texto, criação de imagens, embeddings e muito mais, tudo sem políticas restritivas de conteúdo. Exemplos de integração e SDKs estão disponíveis na [documentação](/overview/getting-started). Nossa referência de API também está disponível como uma [especificação OpenAPI em YAML.](https://api.venice.ai/doc/api/swagger.yaml)
## Autenticação
A API Venice usa chaves de API para autenticação. Crie e gerencie suas chaves de API em suas [configurações de API](https://venice.ai/settings/api).
Todas as requisições da API exigem autenticação Bearer HTTP:
```
Authorization: Bearer VENICE_API_KEY
```
Sua chave de API é um segredo. Não a compartilhe nem a exponha em qualquer código do lado do cliente.
## Compatibilidade com OpenAI
A API da Venice implementa a especificação da API OpenAI, garantindo compatibilidade com clientes e ferramentas existentes do OpenAI. Isso permite que você integre com a Venice usando a familiar interface OpenAI ao mesmo tempo em que acessa os recursos exclusivos da Venice e os modelos sem censura.
### Configuração
Configure seu cliente para usar a URL base da Venice (`https://api.venice.ai/api/v1`) e faça sua primeira requisição:
```bash curl theme={"system"}
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={"system"}
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={"system"}
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)
```
## Recursos específicos da Venice
### Prompts de sistema
A Venice fornece prompts de sistema padrão projetados para garantir respostas de modelos sem censura e naturais. Você tem duas opções para lidar com prompts de sistema:
1. **Comportamento padrão**: Seus prompts de sistema são acrescentados aos padrões da Venice
2. **Comportamento personalizado**: Desabilite completamente os prompts de sistema da Venice
#### Desabilitando os prompts de sistema da Venice
Use a opção `venice_parameters` para remover os prompts de sistema padrão da Venice:
```bash curl theme={"system"}
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={"system"}
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={"system"}
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
}
}
)
```
### Parâmetros da Venice
O objeto `venice_parameters` permite acessar recursos específicos da Venice que não estão disponíveis na API OpenAI padrão:
| Parâmetro | Tipo | Descrição | Padrão |
| ------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `character_slug` | string | O slug de um personagem público da Venice (descobrível como "Public ID" na página do personagem publicado) | - |
| `strip_thinking_response` | boolean | Remove blocos `` da resposta (modelos usando o formato legado de tag ``). Veja [Modelos de raciocínio](/guides/features/reasoning-models). | `false` |
| `disable_thinking` | boolean | Em modelos de raciocínio compatíveis, desabilita o raciocínio e remove os blocos `` da resposta | `false` |
| `enable_web_search` | string | Habilita a busca na web para esta requisição (`off`, `on`, `auto` — auto habilita conforme o critério do modelo)
Preços adicionais por uso se aplicam, veja [preços](/overview/pricing#web-search-and-scraping). | `off` |
| `enable_web_scraping` | boolean | Habilita scraping da web de até 5 URLs detectadas na mensagem do usuário. O conteúdo extraído enriquece respostas e ignora a busca na web. Apenas URLs raspadas com sucesso são cobradas.
Preços adicionais por uso se aplicam, veja [preços](/overview/pricing#web-search-and-scraping). | `false` |
| `enable_x_search` | boolean | Habilita a busca nativa do xAI (web + X/Twitter) para modelos Grok compatíveis (por exemplo, `grok-4-20-beta`). Fornece resultados de busca de maior qualidade usando a infraestrutura de busca do xAI. Quando habilitado, a busca padrão na web da Venice é ignorada.
Preços adicionais por uso se aplicam, veja [preços](/overview/pricing#web-search-and-scraping). | `false` |
| `enable_web_citations` | boolean | Quando a busca na web está habilitada, solicita que o LLM cite suas fontes usando o formato `[REF]0[/REF]` | `false` |
| `include_search_results_in_stream` | boolean | Experimental: Inclui resultados da busca no stream como o primeiro chunk emitido | `false` |
| `return_search_results_as_documents` | boolean | Expõe resultados de busca em uma chamada de ferramenta compatível com OpenAI chamada `venice_web_search_documents` para integração com LangChain | `false` |
| `include_venice_system_prompt` | boolean | Se deve incluir os prompts de sistema padrão da Venice junto com os prompts de sistema especificados | `true` |
Esses parâmetros também podem ser especificados como sufixos de modelo anexados ao nome do modelo (por exemplo, `zai-org-glm-5:enable_web_search=auto`). Veja [Sufixos de recursos do modelo](/api-reference/endpoint/chat/model_feature_suffix) para detalhes.
### Prompt caching
A Venice oferece suporte a prompt caching em modelos selecionados para reduzir latência e custos para conteúdo repetido. Para modelos compatíveis, a Venice armazena automaticamente em cache prompts de sistema — sem necessidade de alterações no código. Você também pode marcar manualmente conteúdo para cache usando a propriedade `cache_control` no conteúdo da mensagem.
| Parâmetro | Tipo | Descrição |
| ------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt_cache_key` | string | Dica opcional de roteamento para melhorar as taxas de acerto no cache. Quando fornecida, a Venice roteia requisições para a mesma infraestrutura de backend, aumentando a probabilidade de acertos no cache em conversas com múltiplos turnos. |
Veja [Prompt caching](/guides/features/prompt-caching) para detalhes sobre como o caching funciona, cobrança e melhores práticas.
## Referência de cabeçalhos de resposta
Todas as respostas da API Venice incluem cabeçalhos HTTP que fornecem metadados sobre a requisição, limites de taxa, informações do modelo e saldo da conta. Além dos códigos de erro retornados das respostas da API, você pode inspecionar esses cabeçalhos para obter o ID único de uma requisição específica da API, monitorar limites de taxa e acompanhar o saldo da sua conta.
A Venice recomenda registrar IDs de requisição (cabeçalho `CF-RAY`) em implantações de produção para uma solução de problemas mais eficiente com nossa equipe de suporte, caso seja necessário.
A tabela abaixo fornece uma referência abrangente de todos os cabeçalhos que você pode encontrar:
| Cabeçalho | Tipo | Finalidade | Quando retornado |
| ------------------------------------------- | ------ | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Cabeçalhos HTTP padrão** | | | |
| `Content-Type` | string | Tipo MIME do corpo da resposta (`application/json`, `text/csv`, `image/png`, etc.) | Sempre |
| `Content-Encoding` | string | Codificação usada para compactar o corpo da resposta (`gzip`, `br`) | Quando o cliente envia o cabeçalho `Accept-Encoding` |
| `Content-Disposition` | string | Como o conteúdo deve ser exibido (por exemplo, `attachment; filename=export.csv`) | Ao baixar arquivos ou exportações |
| `Date` | string | Timestamp formatado em RFC 7231 de quando a resposta foi gerada | Sempre |
| **Identificação da requisição** | | | |
| `CF-RAY` | string | Identificador único desta requisição da API, usado para solução de problemas e suporte | Sempre |
| `x-venice-version` | string | Versão/revisão atual do serviço da API Venice (por exemplo, `20250828.222653`) | Sempre |
| `x-venice-timestamp` | string | Timestamp do servidor quando a requisição foi processada (formato ISO 8601) | Quando o rastreamento de timestamp está habilitado |
| `x-venice-host-name` | string | Nome do host do servidor que processou a requisição | Respostas de erro e cenários de depuração |
| **Informações do modelo** | | | |
| `x-venice-model-id` | string | Identificador único do modelo de IA usado na requisição (por exemplo, `venice-01-lite`) | Endpoints de inferência usando modelos de IA |
| `x-venice-model-name` | string | Nome amigável/de exibição do modelo de IA usado (por exemplo, `Venice Lite`) | Endpoints de inferência usando modelos de IA |
| `x-venice-model-router` | string | Roteador/serviço de backend que lidou com a inferência do modelo | Endpoints de inferência quando informações de roteamento estão disponíveis |
| `x-venice-model-deprecation-warning` | string | Mensagem de aviso para modelos programados para descontinuação | Ao usar um modelo descontinuado |
| `x-venice-model-deprecation-date` | string | Data em que o modelo será descontinuado (data ISO 8601) | Ao usar um modelo descontinuado |
| **Informações de limite de taxa** | | | |
| `x-ratelimit-limit-requests` | number | Número máximo de requisições permitidas na janela de tempo atual | Todas as requisições autenticadas |
| `x-ratelimit-remaining-requests` | number | Número de requisições restantes na janela de tempo atual | Todas as requisições autenticadas |
| `x-ratelimit-reset-requests` | number | Timestamp Unix de quando o limite de requisições é redefinido | Todas as requisições autenticadas |
| `x-ratelimit-limit-tokens` | number | Número máximo de tokens (prompt + completion) permitidos na janela de tempo | Todas as requisições autenticadas |
| `x-ratelimit-remaining-tokens` | number | Número de tokens restantes na janela de tempo atual | Todas as requisições autenticadas |
| `x-ratelimit-reset-tokens` | number | Duração em segundos até o limite de tokens ser redefinido | Todas as requisições autenticadas |
| `x-ratelimit-type` | string | Tipo de limite de taxa aplicado (`user`, `api_key`, `global`) | Quando o limite de taxa é aplicado |
| **Cabeçalhos de paginação** | | | |
| `x-pagination-limit` | number | Número de itens por página | Endpoints paginados |
| `x-pagination-page` | number | Número da página atual (baseado em 1) | Endpoints paginados |
| `x-pagination-total` | number | Número total de itens em todas as páginas | Endpoints paginados |
| `x-pagination-total-pages` | number | Número total de páginas | Endpoints paginados |
| **Informações de saldo da conta** | | | |
| `x-venice-balance-diem` | string | Seu saldo do token DIEM antes do processamento da requisição | Todas as requisições autenticadas |
| `x-venice-balance-usd` | string | Seu saldo de crédito em USD antes do processamento da requisição | Todas as requisições autenticadas |
| **Cabeçalhos de segurança de conteúdo** | | | |
| `x-venice-is-blurred` | string | Indica se a imagem gerada foi borrada devido às políticas de conteúdo (`true`/`false`) | Geração de imagem com Safe Venice habilitado |
| `x-venice-is-content-violation` | string | Indica se o conteúdo viola as políticas de conteúdo da Venice (`true`/`false`) | Endpoints de geração de conteúdo |
| `x-venice-is-adult-model-content-violation` | string | Indica se o conteúdo viola as políticas de conteúdo de modelos adultos (`true`/`false`) | Endpoints de geração de imagem |
| `x-venice-contains-minor` | string | Indica se a imagem contém menores (`true`/`false`) | Endpoints de análise de imagem com detecção de idade |
| **Informações do cliente** | | | |
| `x-venice-middleface-version` | string | Versão do cliente Venice middleface | Requisições de clientes Venice middleface |
| `x-venice-mobile-version` | string | Versão do cliente do aplicativo móvel Venice | Requisições de aplicativos móveis |
| `x-venice-request-timestamp-ms` | number | Timestamp da requisição fornecido pelo cliente em milissegundos | Quando o cliente fornece timestamp na requisição |
| `x-venice-control-instance` | string | Identificador da instância de controle para depuração | Endpoints de geração de imagem para depuração |
| **Cabeçalhos de autenticação** | | | |
| `x-auth-refreshed` | string | Indica que o token de autenticação foi atualizado durante a requisição (`true`/`false`) | Quando os tokens de autenticação são atualizados automaticamente |
| `x-retry-count` | number | Número de tentativas de repetição para a requisição | Quando ocorrem novas tentativas de requisição |
### Notas importantes
* **Capitalização do nome do cabeçalho**: Os cabeçalhos HTTP são case-insensitive, mas a Venice usa minúsculas com hífens para consistência
* **Valores em string**: Valores booleanos em cabeçalhos são retornados como strings (`"true"` ou `"false"`)
* **Valores numéricos**: Números grandes e valores de saldo podem ser retornados como strings para evitar perda de precisão
* **Cabeçalhos opcionais**: Nem todos os cabeçalhos são retornados em todas as respostas; a presença depende do endpoint e do contexto da requisição
* **Compactação**: Use `Accept-Encoding: gzip, br` nas requisições para receber respostas compactadas quando suportado
### Exemplo: Acessando cabeçalhos de resposta
```javascript theme={"system"}
// Após fazer uma requisição à API, acesse os cabeçalhos a partir do objeto de resposta
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');
// Verifique se há avisos de descontinuação de modelo
const deprecationWarning = response.headers.get('x-venice-model-deprecation-warning');
if (deprecationWarning) {
console.warn(`Model Deprecation: ${deprecationWarning}`);
}
```
## Melhores práticas
1. **Limite de taxa**: Monitore os cabeçalhos `x-ratelimit-remaining-requests` e `x-ratelimit-remaining-tokens` e implemente backoff exponencial
2. **Monitoramento de saldo**: Acompanhe os cabeçalhos `x-venice-balance-usd` e `x-venice-balance-diem` para evitar interrupções de serviço
3. **Prompts de sistema**: Teste com e sem os prompts de sistema da Venice para encontrar o melhor ajuste para seu caso de uso
4. **Chaves de API**: Mantenha suas chaves de API seguras e faça rotação regularmente
5. **Registro de requisições**: Registre os valores do cabeçalho `CF-RAY` para solucionar problemas com o suporte
6. **Descontinuação de modelos**: Verifique os cabeçalhos `x-venice-model-deprecation-warning` ao usar modelos
## Diferenças em relação à API da OpenAI
Embora a Venice mantenha alta compatibilidade com a especificação da API OpenAI, há algumas diferenças importantes:
1. **venice\_parameters**: Configurações adicionais como `enable_web_search`, `character_slug` e `strip_thinking_response` para funcionalidade estendida
2. **Prompts de sistema**: A Venice acrescenta seus prompts de sistema a padrões otimizados para respostas sem censura (desabilite com `include_venice_system_prompt: false`)
3. **Ecossistema de modelos**: A Venice oferece sua própria [linha de modelos](/overview/models) incluindo modelos sem censura e de raciocínio — use os IDs de modelo da Venice em vez dos mapeamentos da OpenAI
4. **Cabeçalhos de resposta**: Cabeçalhos exclusivos para rastreamento de saldo (`x-venice-balance-usd`, `x-venice-balance-diem`), avisos de descontinuação de modelos e flags de segurança de conteúdo
5. **Políticas de conteúdo**: Políticas mais permissivas com modelos dedicados sem censura e filtragem de conteúdo opcional
## Estabilidade da API
A Venice mantém compatibilidade retroativa para endpoints e parâmetros v1. Para política de ciclo de vida de modelos, avisos de descontinuação e orientações de migração, veja [Descontinuações](/overview/deprecations).
## Especificação OpenAPI e dados brutos
Para acesso programático à documentação e aos dados da API Venice — incluindo uso com RAG (Retrieval-Augmented Generation) — os seguintes recursos estão disponíveis:
* [Especificação OpenAPI (YAML)](https://api.venice.ai/doc/api/swagger.yaml) — a especificação completa da API em formato YAML
* [Fonte da documentação da API](https://github.com/veniceai/api-docs/archive/refs/heads/main.zip) — todas as páginas de documentação (formato `.mdx`) como um arquivo para download
***
Campos de requisição não listados nesta documentação podem ser passados, mas não são validados nem garantidos para funcionar.