venice-api-kit

Complete Venice AI API toolkit - image generation, video, audio, embeddings, transcription, characters, models, and admin functions. Privacy-focused inference with zero data retention.

# Venice API Kit

Complete toolkit for the entire Venice AI API. Includes all inference endpoints (image, video, audio, embeddings), discovery tools (models, characters), and admin functions (billing, usage, API keys).

**API Base URL:** `https://api.venice.ai/api/v1`
**Documentation:** [docs.venice.ai](https://docs.venice.ai)

## Setup

1. Get your API key from [venice.ai](https://venice.ai) → Settings → API Keys
2. Set the environment variable:

```bash
export VENICE_API_KEY="your_api_key_here"
```

Or configure in `~/.openclaw/openclaw.json`:

```json5
{
  skills: {
    entries: {
      "venice-api-kit": {
        apiKey: "your_api_key_here"
      }
    }
  }
}
```

---

## Image Generation

Generate images using Venice's image models. Returns base64 image data.

```bash
uv run {baseDir}/scripts/image_generate.py --prompt "a serene mountain landscape at sunset"
```

**Options:**

- `--prompt` (required): Description of the image (max 7500 chars, model-dependent)
- `--output`: Output filename (default: auto-generated timestamp)
- `--model`: Model ID (default: `flux-2-max`)
- `--size`: Image size: `1024x1024`, `1536x1024`, `1024x1536`, `1792x1024`, `1024x1792` (default: `1024x1024`)
- `--style-id`: Style preset ID (use `--list-styles` to see available)
- `--negative-prompt`: What to avoid in the image
- `--seed`: Seed for reproducible generation

**List available styles:**

```bash
uv run {baseDir}/scripts/image_generate.py --list-styles
```

---

## Image Upscaling

Upscale images 1-4x with optional AI enhancement. Returns binary PNG.

```bash
uv run {baseDir}/scripts/image_upscale.py --image input.png --scale 2
```

**Options:**

- `--image` (required): Input image path or URL
- `--output`: Output filename (default: `upscaled-{timestamp}.png`)
- `--scale`: Scale factor 1-4 (default: `2`). Scale of 1 requires `--enhance`
- `--enhance`: Enable AI enhancement during upscaling
- `--enhance-creativity`: How much AI can change (0-1, higher = more creative)
- `--enhance-prompt`: Style to apply (e.g., "gold", "marble", "cinematic")
- `--replication`: Preserve original lines/noise (0-1, higher = less hallucination)

**Example with enhancement:**

```bash
uv run {baseDir}/scripts/image_upscale.py --image photo.png --scale 2 --enhance --enhance-prompt "cinematic lighting"
```

---

## Image Editing

Edit images with AI using text prompts. Returns binary PNG.

```bash
uv run {baseDir}/scripts/image_edit.py --image photo.png --prompt "add sunglasses"
```

**Options:**

- `--image` (required): Input image path or URL
- `--prompt` (required): Edit instructions (e.g., "remove the tree", "change sky to sunset")
- `--output`: Output filename (default: `edited-{timestamp}.png`)
- `--model`: Edit model (default: `qwen-edit`). Available: `qwen-edit`, `flux-2-max-edit`, `gpt-image-1-5-edit`, `nano-banana-pro-edit`, `seedream-v4-edit`
- `--aspect-ratio`: Output aspect ratio: `auto`, `1:1`, `3:2`, `16:9`, `21:9`, `9:16`, `2:3`, `3:4`

---

## Background Removal

Remove backgrounds from images. Returns binary PNG with transparency.

```bash
uv run {baseDir}/scripts/image_background_remove.py --image photo.png
```

**Options:**

- `--image` (required): Input image path or URL
- `--output`: Output filename (default: `no-background-{timestamp}.png`)

---

## Text-to-Speech

Convert text to speech with multiple voices and formats. Returns binary audio.

```bash
uv run {baseDir}/scripts/audio_speech.py --text "Hello, welcome to Venice AI"
```

**Options:**

- `--text` (required): Text to convert (max 4096 characters)
- `--output`: Output filename (default: `speech-{timestamp}.{format}`)
- `--voice`: Voice ID (default: `af_nicole`)
- `--model`: TTS model (default: `tts-kokoro`)
- `--speed`: Speed multiplier 0.25-4.0 (default: `1.0`)
- `--format`: Audio format: `mp3`, `opus`, `aac`, `flac`, `wav`, `pcm` (default: `mp3`)
- `--streaming`: Stream audio sentence by sentence

**Available voices:**

- American Female: `af_alloy`, `af_aoede`, `af_bella`, `af_heart`, `af_jadzia`, `af_jessica`, `af_kore`, `af_nicole`, `af_nova`, `af_river`, `af_sarah`, `af_sky`
- American Male: `am_adam`, `am_echo`, `am_eric`
- British Female: `bf_emma`, `bf_isabella`, `bf_alice`
- British Male: `bm_george`, `bm_lewis`, `bm_daniel`

---

## Audio Transcription

Transcribe audio files to text using Whisper-based speech recognition.

```bash
uv run {baseDir}/scripts/transcribe.py --file audio.mp3
```

**Options:**

- `--file` (required): Audio file to transcribe (WAV, MP3, FLAC, M4A, AAC)
- `--output`: Save transcription to file
- `--model`: ASR model (default: `openai/whisper-large-v3`)
- `--format`: Output format: `json` or `text` (default: `json`)
- `--timestamps`: Include word/segment timestamps
- `--language`: Language hint (ISO 639-1: en, es, fr, etc.)

---

## Embeddings

Generate vector embeddings for RAG applications.

```bash
uv run {baseDir}/scripts/embeddings.py --text "Your text to embed"
```

**Options:**

- `--text`: Text to embed (use this OR `--file`)
- `--file`: Read text from file
- `--output`: Save embeddings to JSON file
- `--model`: Embedding model (default: `text-embedding-3-small`)

---

## Video Generation

Generate videos from text prompts. Some models require a reference image. Async with polling.

**Text-to-video:**

```bash
uv run {baseDir}/scripts/video_generate.py --prompt "a cat playing piano"
```

**Image-to-video (requires reference image):**

```bash
uv run {baseDir}/scripts/video_generate.py --prompt "a cat playing piano" --image reference.png
```

**Options:**

- `--prompt` (required): Video description (max 2500 characters)
- `--image`: Reference image (path or URL) - required for image-to-video models
- `--output`: Output filename (default: `venice-video-{timestamp}.mp4`)
- `--model`: Video model (default: `wan-2.6-image-to-video`). Also: `wan-2.6-text-to-video`, `wan-2.6-flash-image-to-video`
- `--duration`: Video duration: `5s` or `10s` (default: `5s`)
- `--resolution`: Resolution: `480p`, `720p`, `1080p` (default: `720p`)
- `--aspect-ratio`: Aspect ratio (e.g., `16:9`, `9:16`, `1:1`)
- `--negative-prompt`: What to avoid in the video
- `--max-wait`: Max seconds to wait for completion (default: `600`)

---

## Models Explorer

List and explore all available Venice AI models. No API key required.

```bash
uv run {baseDir}/scripts/models.py
```

**Options:**

- `--type`: Filter by type: `all`, `text`, `image`, `video`, `tts`, `asr`, `embedding`, `code`, `upscale`, `inpaint` (default: `all`)
- `--format`: Output format: `table`, `json`, `names` (default: `table`)
- `--output`: Save to file

**Examples:**

```bash
uv run {baseDir}/scripts/models.py --type image
uv run {baseDir}/scripts/models.py --format json --output models.json
```

---

## Characters Browser

Browse and discover Venice AI character personas.

```bash
uv run {baseDir}/scripts/characters.py
```

**Options:**

- `--search`: Search by name or description
- `--tag`: Filter by tag
- `--limit`: Max results (default: 20)
- `--format`: Output format: `table`, `json`, `list` (default: `table`)
- `--output`: Save to file

**Examples:**

```bash
uv run {baseDir}/scripts/characters.py --search "coding"
uv run {baseDir}/scripts/characters.py --tag "assistant" --format json
```

---

## Admin: Check Balance

Check your DIEM and USD balances. **Requires Admin API key.**

```bash
uv run {baseDir}/scripts/balance.py
```

Shows current balance, consumption currency, and DIEM epoch allocation.

---

## Admin: Usage History

View detailed usage history with filtering. **Requires Admin API key.**

```bash
uv run {baseDir}/scripts/usage.py
```

**Options:**

- `--currency`: Filter by currency: `DIEM`, `USD`, `VCU` (default: `DIEM`)
- `--start-date`: Start date (ISO format: 2024-01-01)
- `--end-date`: End date (ISO format: 2024-12-31)
- `--limit`: Results per page, max 200 (default: 50)
- `--page`: Page number (default: 1)
- `--sort`: Sort order: `asc`, `desc` (default: `desc`)
- `--format`: Output format: `json`, `csv` (d