---
name: Veniceai
description: Use when building AI applications with text, image, audio, or video generation. Reach for Venice when you need OpenAI-compatible APIs, uncensored models, private inference, web search/scraping, function calling, structured responses, or agent integrations (LangChain, CrewAI, etc.). Also use for crypto RPC calls, file inputs, embeddings, and wallet-funded workflows.
metadata:
    mintlify-proj: veniceai
    version: "1.0"
---

# Venice AI Skill

## Product Summary

Venice AI is an OpenAI-compatible API platform providing private, unrestricted access to 250+ text, image, audio, and video models. Agents use Venice to build chat applications, generate images, create videos, transcribe audio, and run AI agents with web search, file inputs, and structured responses. The API endpoint is `https://api.venice.ai/api/v1`. Authentication uses Bearer tokens (API keys). Key files: environment variable `VENICE_API_KEY`. Primary docs: https://docs.venice.ai

## When to Use

Use Venice AI when:
- Building chat applications with OpenAI SDK compatibility (just change base URL)
- Generating, upscaling, or editing images from text prompts
- Creating videos from text or images (async queue system)
- Transcribing audio or generating speech with 50+ voices
- Running AI agents with LangChain, CrewAI, LlamaIndex, or other frameworks
- Needing web search, web scraping, or file inputs in chat requests
- Requiring structured JSON responses with guaranteed schemas
- Building reasoning-heavy workflows with extended thinking models
- Querying blockchain data via crypto RPC endpoints
- Paying per request with USDC on Base (x402 wallet integration)
- Needing uncensored models without restrictive content policies

## Quick Reference

### API Endpoints

| Endpoint | Purpose |
|----------|---------|
| `POST /chat/completions` | Text generation, vision, tool use, streaming |
| `POST /image/generate` | Text-to-image generation |
| `POST /image/upscale` | Enhance image resolution |
| `POST /image/edit` | Inpaint/modify existing images |
| `POST /audio/speech` | Text-to-speech with 50+ voices |
| `POST /audio/transcriptions` | Speech-to-text transcription |
| `POST /video/queue` | Queue text-to-video or image-to-video jobs |
| `POST /video/retrieve` | Fetch completed video generation results |
| `POST /embeddings/generate` | Generate text embeddings |
| `POST /crypto/rpc/{chain}` | JSON-RPC 2.0 calls (11 chains supported) |

### Authentication

```bash
# Set API key in environment
export VENICE_API_KEY='your-api-key-here'

# Or in .env file
VENICE_API_KEY=your-api-key-here
```

All requests require header: `Authorization: Bearer $VENICE_API_KEY`

### Common Model IDs

| Model | Use Case |
|-------|----------|
| `zai-org-glm-5` | Default general-purpose model |
| `zai-org-glm-5-1` | Latest GLM model |
| `kimi-k2-6` | Strong reasoning for complex tasks |
| `claude-opus-4-8` | High-intelligence Anthropic model |
| `venice-uncensored-1-2` | Venice's uncensored model |
| `qwen-image` | Highest quality image generation |
| `venice-sd35` | Fast, versatile image generation |

### Venice Parameters (Special Features)

Pass via `venice_parameters` in request body or as model suffix:

| Parameter | Type | Purpose |
|-----------|------|---------|
| `enable_web_search` | string | `"off"`, `"on"`, or `"auto"` for real-time web search |
| `enable_web_scraping` | boolean | Fetch and read URLs in user message |
| `enable_web_citations` | boolean | Request source citations in response |
| `include_venice_system_prompt` | boolean | Include Venice's default system prompts (default: `true`) |
| `character_slug` | string | Use a published Venice character persona |
| `disable_thinking` | boolean | Disable reasoning/thinking on supported models |
| `strip_thinking_response` | boolean | Remove `<think></think>` blocks from output |

### Response Headers to Monitor

| Header | Purpose |
|--------|---------|
| `x-ratelimit-remaining-requests` | Requests left in current window |
| `x-ratelimit-remaining-tokens` | Tokens left in current window |
| `x-ratelimit-reset-requests` | Unix timestamp when limit resets |
| `x-venice-balance-usd` | USD credit balance before request |
| `x-venice-balance-diem` | DIEM token balance before request |
| `CF-RAY` | Unique request ID for support debugging |
| `x-venice-model-deprecation-warning` | Warning if model is deprecated |

## Decision Guidance

### When to Use X vs Y

| Scenario | Use | Why |
|----------|-----|-----|
| Need OpenAI compatibility | Venice with OpenAI SDK | Drop-in replacement, just change base URL |
| Need uncensored responses | `venice-uncensored-1-2` model | Venice's own uncensored model |
| Need reasoning/thinking | `kimi-k2-6` or models with `disable_thinking: false` | Extended thinking for complex problems |
| Need structured JSON output | `response_format` with `json_schema` | Guaranteed schema compliance, less hallucination |
| Need function calling | `tools` parameter in chat/completions | For agent workflows and tool use |
| Need web search | `enable_web_search: "auto"` in venice_parameters | Real-time data without extra API keys |
| Need file analysis | File inputs in message content | Supports PDF, Office, code, text (up to 25MB) |
| Need image generation | `POST /image/generate` | Text-to-image with multiple model options |
| Need video generation | `POST /video/queue` + `POST /video/retrieve` | Async job queue for long-running tasks |
| Need blockchain data | `POST /crypto/rpc/{chain}` | Direct JSON-RPC 2.0 access to 11 chains |
| Need pay-per-request (no account) | x402 wallet integration | USDC on Base, no Venice account needed |
| Need daily allowance | DIEM staking | Fixed daily inference budget |

## Workflow

### 1. Set Up Authentication
- Generate API key at https://venice.ai/settings/api
- Store in `VENICE_API_KEY` environment variable
- Verify key type: "Admin" (can manage keys) or "Inference Only" (read-only)

### 2. Choose Your Integration Method
- **Direct HTTP**: Use cURL or raw fetch requests
- **OpenAI SDK**: Use OpenAI Python/Node.js SDK with Venice base URL
- **Framework**: LangChain, CrewAI, LlamaIndex, Vercel AI SDK, etc.

### 3. Make Your First Request
```bash
curl https://api.venice.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org-glm-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

### 4. Check Response Headers
- Monitor `x-ratelimit-remaining-requests` and `x-ratelimit-remaining-tokens`
- Track `x-venice-balance-usd` and `x-venice-balance-diem` to avoid service interruption
- Log `CF-RAY` header for support debugging

### 5. Enable Advanced Features (Optional)
- Add `venice_parameters` for web search, scraping, or character personas
- Use `response_format` with `json_schema` for structured outputs
- Add `tools` array for function calling in agent workflows
- Set `stream: true` for real-time streaming responses

### 6. Handle Rate Limits
- Implement exponential backoff for 429 errors
- Check `x-ratelimit-reset-requests` header for retry timing
- Monitor token usage with `x-ratelimit-remaining-tokens`

### 7. Verify and Deploy
- Test with small requests before scaling
- Log request IDs (`CF-RAY`) in production
- Monitor balance headers to prevent service interruption
- Check for model deprecation warnings in response headers

## Common Gotchas

- **API Key Exposure**: Never commit API keys to version control. Use environment variables or `.env` files with `.gitignore`.
- **Base URL Required**: Must use `https://api.venice.ai/api/v1` as base URL. OpenAI's default URL won't work.
- **Venice System Prompts**: By default, Venice appends its own system prompts to yours. Disable with `include_venice_system_prompt: false` if you want full control.
- **Structured Responses Not Universal**: `response_format` with `json_schema` only works on models with `supportsResponseSchema: true`. Check model capabilities via `/models/list` endpoint.
- **Image Generation Returns Base64**: Image endpoints return base64-encoded data in `images` array. Decode before saving/displaying.
- **Video Generation is Async**: Video jobs are queued. Use `/video/queue` to start, then `/video/retrieve` to poll for results. Not synchronous like chat.
- **Web Search Costs Extra**: `enable_web_search` and `enable_web_scraping` incur additional usage-based charges beyond base model costs.
- **File Inputs Have Size Limits**: Maximum 25MB per file. Supported formats: PDF, Office docs, code, text files.
- **Rate Limits Vary by Model**: Different models have different RPM (requests per minute) and TPM (tokens per minute) limits. Check your tier at https://venice.ai/settings/api.
- **Streaming Doesn't Include Usage**: When `stream: true`, token counts are not available in real-time. Use `stream_options: {"include_usage": true}` to get final usage in last chunk.
- **Model IDs Change**: Check `/models/list` endpoint for current available models. Some models are deprecated. Watch for `x-venice-model-deprecation-warning` headers.
- **Crypto RPC Requires Specific Chain**: Use correct chain ID in URL path (e.g., `/crypto/rpc/ethereum-mainnet`). Invalid chains return 404.
- **x402 Wallet Integration**: Requires USDC on Base chain. No Venice account needed, but wallet must have sufficient balance.

## Verification Checklist

Before submitting work with Venice AI:

- [ ] API key is set in environment variable or `.env` file (not hardcoded)
- [ ] Base URL is `https://api.venice.ai/api/v1` (not OpenAI's URL)
- [ ] Model ID exists and is available (check `/models/list` if unsure)
- [ ] Request includes required `messages` array with at least one user message
- [ ] If using `response_format`, model supports `supportsResponseSchema: true`
- [ ] If using `tools`, model supports `supportsFunctionCalling: true`
- [ ] If using web search, `enable_web_search` is set to `"auto"` or `"on"` (not `"off"`)
- [ ] If streaming, handling chunks correctly (check for `delta.content` in each chunk)
- [ ] If generating images, decoding base64 before saving
- [ ] If generating videos, polling `/video/retrieve` endpoint (not expecting sync response)
- [ ] Rate limit headers are being monitored in production
- [ ] Balance headers (`x-venice-balance-usd`, `x-venice-balance-diem`) are checked to prevent service interruption
- [ ] Request ID (`CF-RAY` header) is logged for debugging
- [ ] Error handling includes retry logic with exponential backoff for 429/500/503 errors
- [ ] No deprecated models are being used (check for deprecation warnings in headers)

## Resources

**Comprehensive Navigation**: https://docs.venice.ai/llms.txt — Full page-by-page listing of all documentation

**Critical Pages**:
1. [API Reference](https://docs.venice.ai/api-reference/api-spec) — Complete endpoint documentation, authentication, response headers, and best practices
2. [Chat Completions Endpoint](https://docs.venice.ai/api-reference/endpoint/chat/completions) — Detailed chat API with all parameters, examples, and response formats
3. [Models Catalog](https://docs.venice.ai/overview/models) — Browse all 250+ models with capabilities, pricing, and context limits

---

> For additional documentation and navigation, see: https://docs.venice.ai/llms.txt