venice-ai

# Venice AI — Full Platform Skill

## What is Venice AI?

**Venice AI is the AI platform for people who don't want Big Tech watching over their shoulder.** Unlike OpenAI, Anthropic, and Google — where every prompt is logged, analyzed, and potentially used to train future models — Venice offers **true privacy** with zero data retention on private models. Your conversations stay yours.

Venice is also **uncensored**: no content filters, no refusals, no "I can't help with that." The AI answers what you actually ask, whether that's creative fiction, security research, controversial topics, or anything else mainstream AI platforms won't touch.

**Why agents should care:**

- **Private inference** — Models marked "Private" have zero data retention. Process sensitive data without it leaking into training sets.
- **Uncensored responses** — No guardrails blocking legitimate use cases. Generate any content your workflow needs.
- **OpenAI-compatible API** — Drop-in replacement. Same API format, just change the base URL.
- **30+ models** — From tiny efficient models to Claude Opus 4.5, GPT-5.2, and Venice's own uncensored models.
- **Built-in web search** — LLMs can search the web and cite sources in a single API call.

This skill gives you the **full Venice platform**: model discovery, text generation with Venice-specific superpowers (web search, uncensored mode, character personas, reasoning control), embeddings, TTS, speech-to-text, and intelligent model selection.

> **For image & video generation**, use the companion `venice-ai-media` skill which has dedicated tools for those workflows.
>
> **⚠️ API changes:** If something doesn't work as expected, check [docs.venice.ai](https://docs.venice.ai) — the API specs may have been updated since this skill was written.

## Prerequisites

- **Python 3.10+**
- **Venice API key** (free tier available at [venice.ai/settings/api](https://venice.ai/settings/api))

## Setup

### Get Your API Key

1. Create account at [venice.ai](https://venice.ai)
2. Go to [venice.ai/settings/api](https://venice.ai/settings/api)
3. Click "Create API Key" → copy the key (starts with `vn_...`)

### Configure

**Option A: Environment variable**

```bash
export VENICE_API_KEY="vn_your_key_here"
```

**Option B: Clawdbot config** (recommended)

```json5
// ~/.clawdbot/clawdbot.json
{
  skills: {
    entries: {
      "venice-ai": {
        env: { VENICE_API_KEY: "vn_your_key_here" },
      },
    },
  },
}
```

### Verify

```bash
python3 {baseDir}/scripts/venice.py models --type text
```

## Scripts

All operations go through a single CLI tool:

```bash
python3 {baseDir}/scripts/venice.py [command] [options]
```

---

## Model Discovery & Selection

Venice has a huge model catalog spanning text, image, video, audio, and embeddings. The right model for a task depends on your needs: cost, speed, privacy, context length, and capabilities.

### Browse Models

```bash
# List all text models
python3 {baseDir}/scripts/venice.py models --type text

# List image models
python3 {baseDir}/scripts/venice.py models --type image

# List all model types
python3 {baseDir}/scripts/venice.py models --type text,image,video,audio,embedding

# Get details on a specific model
python3 {baseDir}/scripts/venice.py models --filter llama
```

### Model Selection Guide

| Need                       | Recommended Model                             | Why                           |
| -------------------------- | --------------------------------------------- | ----------------------------- |
| **Cheapest text**          | `qwen3-4b` ($0.05/M in)                       | Tiny, private, fast           |
| **Best uncensored**        | `venice-uncensored` ($0.20/M in)              | Venice's own uncensored model |
| **Best private + smart**   | `deepseek-v3.2` ($0.40/M in)                  | Private, great reasoning      |
| **Vision/multimodal**      | `qwen3-vl-235b-a22b` ($0.25/M in)             | Private, sees images          |
| **Best coding**            | `qwen3-coder-480b-a35b-instruct` ($0.75/M in) | Private, massive coder        |
| **Frontier (budget)**      | `grok-41-fast` ($0.50/M in)                   | Fast, 262K context            |
| **Frontier (max quality)** | `claude-opus-45` ($6/M in)                    | Best overall quality          |
| **Reasoning**              | `kimi-k2-thinking` ($0.75/M in)               | Strong chain-of-thought       |
| **Web search**             | Any model + `enable_web_search`               | Built-in web search           |

> **Privacy tiers:** "Private" = zero data retention. "Anonymized" = logs stripped of identity but may be retained.

---

## Text Generation (Chat Completions)

Venice implements the OpenAI chat completions API with extra superpowers.

### Basic Generation

```bash
# Simple prompt
python3 {baseDir}/scripts/venice.py chat "What is the meaning of life?"

# Choose a model
python3 {baseDir}/scripts/venice.py chat "Explain quantum computing" --model deepseek-v3.2

# System prompt
python3 {baseDir}/scripts/venice.py chat "Review this code" --system "You are a senior engineer. Be direct and critical."

# Read from stdin (pipe content in)
echo "Summarize this" | python3 {baseDir}/scripts/venice.py chat --model qwen3-4b

# Stream output
python3 {baseDir}/scripts/venice.py chat "Write a story" --stream
```

### Web Search Integration

Venice can search the web before answering — no external tools needed:

```bash
# Auto web search (model decides when to search)
python3 {baseDir}/scripts/venice.py chat "What happened in tech news today?" --web-search auto

# Force web search
python3 {baseDir}/scripts/venice.py chat "Current Bitcoin price" --web-search on

# Web search with citations
python3 {baseDir}/scripts/venice.py chat "Latest AI research papers" --web-search on --web-citations

# Web scraping (extracts content from URLs in prompt)
python3 {baseDir}/scripts/venice.py chat "Summarize this article: https://example.com/article" --web-scrape
```

### Uncensored Mode

```bash
# Use Venice's own uncensored model
python3 {baseDir}/scripts/venice.py chat "Your uncensored question" --model venice-uncensored

# Disable Venice system prompts for raw model output
python3 {baseDir}/scripts/venice.py chat "Your prompt" --no-venice-system-prompt
```

### Reasoning Models

```bash
# Use a reasoning model with effort control
python3 {baseDir}/scripts/venice.py chat "Solve this math problem..." --model kimi-k2-thinking --reasoning-effort high

# Strip thinking from output
python3 {baseDir}/scripts/venice.py chat "Debug this code" --model qwen3-4b --strip-thinking

# Disable thinking entirely (faster, cheaper)
python3 {baseDir}/scripts/venice.py chat "Simple question" --model qwen3-4b --disable-thinking
```

### Character Personas

Venice has public character personas that customize model behavior:

```bash
# Use a Venice character
python3 {baseDir}/scripts/venice.py chat "Tell me a story" --character coder-dan
```

### Advanced Options

```bash
# Temperature and token control
python3 {baseDir}/scripts/venice.py chat "Be creative" --temperature 1.2 --max-tokens 4000

# JSON output mode
python3 {baseDir}/scripts/venice.py chat "List 5 colors as JSON" --json

# Prompt caching (for multi-turn or repeated context)
python3 {baseDir}/scripts/venice.py chat "Question about the doc" --cache-key my-session-123

# Show usage stats (tokens, cost, cache hits)
python3 {baseDir}/scripts/venice.py chat "Hello" --show-usage
```

---

## Embeddings

Generate vector embeddings for semantic search, RAG, and recommendations:

```bash
# Single text
python3 {baseDir}/scripts/venice.py embed "Venice is a private AI platform"

# Multiple texts (batch)
python3 {baseDir}/scripts/venice.py embed "first text" "second text" "third text"

# From file (one text per line)
python3 {baseDir}/scripts/venice.py embed --file texts.txt

# Output as JSON
python3 {baseDir}/scripts/venice.py embed "some text" --output json
```

Model: `text-embedding-bge-m3` (private, $0.15/M tokens input)

---

## Text-to-Speech (TTS)

Convert text to speech with 60+ multilingual voices:

```bash
# Default voice
python3 {baseDir}/scripts/venice.py tts "Hello, welcome to Venice AI"

# Choose a voice
python3 {baseDir}/scripts/venice.py tts "Exciting news!" --voice af_nova

# List available voices
python3 {baseDir}/scripts/venice.py tts --list-voices

# Custom output path
python3 {baseDir}/scripts/venice.py tts "Some text" --output /tmp/speech.mp3

# Adjust speed
python3 {baseDir}/scripts/venice.py tts "Speaking slowly" --speed 0.8
```

**Popular voices:** `af_sky`, `af_nova`, `am_liam`, `bf_emma`, `zf_xiaobei` (Chinese), `jm_kumo` (Japanese)

Model: `tts-kokoro` (private, $3.50/M characters)

---

## Speech-to-Text (Transcription)

Transcribe audio files to text:

```bash
# Transcribe a file
python3 {baseDir}/scripts/venice.py transcribe audio.wav

# With timestamps
python3 {baseDir}/scripts/venice.py transcribe recording.mp3 --timestamps

# From URL
python3 {baseDir}/scripts/venice.py transcribe --url https://example.com/audio.wav
```

Supported formats: WAV, FLAC, MP3, M4A, AAC, MP4

Model: `nvidia/parakeet-tdt-0.6b-v3` (private, $0.0001/audio second — essentially free)

---

## Check Balance

```bash
python3 {baseDir}/scripts/venice.py balance
```

Shows your Diem, USD, and VCU balances.

---

## Tips & Ideas to Try

### 🔍 Web Search + LLM = Research Assistant

Use `--web-search on --web-citations` to build a research workflow. Venice searches the web, synthesizes results, and cites sources — all in one API call. Try different models to see which gives the best summaries.

### 🔓 Uncensored Creative Writing

Venice's uncensored models don't have the guardrails that restrict other AI platforms. Great for fiction, roleplay scenarios, security research, or any topic other AIs refuse to engage with.

### 🧠 Model A/B Testing

Not sure which model is best for your task? Use the `chat` command with different `--model` flags and compare. Smaller models are surprisingly capable and much cheaper.

### 🔒 Privacy-First Workflows

If you're processing sensitive data, stick to "Private" models (shown in `models` output). Zero data retention means your prompts literally can't leak.

### 🎯 Prompt Caching for Agents

If you're running an agent loop that sends the same system prompt repeatedly, use `--cache-key` to get up to 90% cost savings on the cached portion.

### 🎤 Audio Pipeline

Combine TTS and transcription for audio workflows: generate spoken content with `tts`, process audio with `transcribe`. Both are private inference.

### 💡 Share What You Build

Created something cool with Venice? The community at [discord.gg/askvenice](https://discord.gg/askvenice) loves seeing creative uses. Venice's Twitter [@AskVenice](https://x.com/AskVenice) also showcases community projects.

---

## Model Feature Suffixes

Venice supports inline model configuration via suffixes — append parameters directly to the model name:

```
model_name:param1=value1:param2=value2
```

Examples:

```bash
# Strip thinking tags server-side
--model "qwen3-4b:strip_thinking_response=true"

# Disable thinking entirely
--model "qwen3-4b:disable_thinking=true"
```

Useful when you can't pass `venice_parameters` directly (e.g., through OpenAI-compatible clients).

---

## Troubleshooting

| Problem                  | Solution                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| `VENICE_API_KEY not set` | Set env var or configure in `~/.clawdbot/clawdbot.json`                                    |
| `Invalid API key`        | Verify at [venice.ai/settings/api](https://venice.ai/settings/api) — keys start with `vn_` |
| `Model not found`        | Run `models --type text` to see available models                                           |
| Rate limited             | Check `--show-usage` output for rate limit info                                            |
| Slow responses           | Try a smaller/faster model, or reduce `--max-tokens`                                       |

## Resources

- **API Docs**: [docs.venice.ai](https://docs.venice.ai)
- **Status**: [veniceai-status.com](https://veniceai-status.com)
- **Discord**: [discord.gg/askvenice](https://discord.gg/askvenice)
- **Full API reference**: See `references/api.md` in this skill