venice

What this skill does

# Venice AI

Privacy-first AI platform. OpenAI-compatible API at `https://api.venice.ai/api/v1`. Four privacy tiers — anonymized, private, TEE, E2EE. Zero data retention. No content filtering on most models.

This skill covers everything **except** chat completions. For chat, the right path is BYOK via the platform's `custom_models` tool — see "Chat onboarding" below.

## Quick capability map

| Surface | Function |
|---|---|
| Catalog | `list_models`, `list_model_traits`, `list_image_styles`, `list_characters` |
| Account | `account_balance` (balance + tier + rate-limit count) |
| Image | `image_generate`, `image_edit`, `image_upscale` |
| Audio | `tts`, `transcribe` |
| Embeddings | `embeddings` (default `text-embedding-bge-m3`, dim 1024) |
| Chat probe | `chat_with_venice_parameters` (one-shot) |
| Video | `video_quote`, `video_queue`, `video_retrieve`, `video_complete`, `video_generate` (full loop), `video_transcribe_youtube` |

Endpoints intentionally NOT wrapped: standalone `/tools/search/web` (Venice removed it; use `enable_web_search` via venice_parameters in chat instead), admin-scoped `/api_keys` and `/billing/usage` (require an admin key the BYOK key can't use).

## Setup

1. User goes to <https://venice.ai/settings/api>, creates a key.
2. Add the key to the workspace via secure input — **never paste in chat**:
   - If the user wants chat: call `custom_models(action='add_template', vendor='venice')`. Auto-pops the secure input and registers Venice for chat completions in one shot.
   - If the user only wants this skill (image/audio/embeddings): call `request_env_input(env_vars=[{key='VENICE_API_KEY', label='Venice API Key', required=True}], reason='Use Venice image/audio/embeddings via the venice skill')`.
3. The skill resolves the key in this order: `VENICE_API_KEY` → any `CUSTOM_KEY_VENICE_*` from BYOK registration. Either path works; both is fine.

`account_balance()` is the cheapest probe (200 OK = key works).

## Usage

```python
import sys
sys.path.insert(0, "/data/workspace/skills/venice")
from exports import (
    list_models, image_generate, image_edit, image_upscale,
    tts, transcribe, embeddings,
    list_image_styles, list_characters, list_model_traits,
    account_balance, chat_with_venice_parameters,
)
```

### Browse models

```python
# Default returns text models only — pass type_filter to scope.
text_vision = list_models(type_filter="text", only_capabilities=["supportsVision"])
images = list_models(type_filter="image")          # 28 image models
ttss   = list_models(type_filter="tts")            # 10 voices
private_only = list_models(type_filter="text", privacy="private")
all_models   = list_models(type_filter="all")      # ~244 entries — heavy, use sparingly
```

Each entry: `id, type, name, description, privacy, context_tokens, max_completion_tokens, capabilities, pricing_input_usd, pricing_output_usd, pricing_cache_input_usd, traits`.

`list_model_traits()` returns Venice's curated picks: `default`, `most_intelligent`, `most_uncensored`, `default_reasoning`, `default_vision`, `default_code`, `function_calling_default`, `fastest`. Use this when the user says "give me Venice's smartest model" — don't guess.

### Image generation

**Don't guess model IDs.** Venice rotates image models often (e.g. `flux-dev-uncensored` no longer exists; `flux-2-pro` does). Always confirm with `list_models(type_filter="image")` before passing a non-default `model=`. Same rule for `image_edit` and `image_upscale`.

```python
g = image_generate(
    "neon cyberpunk cat in the rain",
    model="venice-sd35",       # default; see list_models(type_filter='image') for others
    width=1024, height=1024,   # any aspect-ratio Venice supports
    steps=20,
    style_preset="Cinematic",  # see list_image_styles() for the 76 presets
    save_path="cat.webp",      # → output/images/cat.webp (platform convention)
)
print(g["saved_path"])
```

Returns `{id, model, prompt, width, height, image_b64 (always), saved_path, timing}`.

### Image edit

```python
e = image_edit(
    "output/images/cat.webp",
    "make the rain heavier and add lightning",
    model="qwen-edit",         # default ($0.04/edit). Other valid IDs:
                                # firered-image-edit, grok-imagine-edit,
                                # qwen-image-2-edit, qwen-image-2-pro-edit,
                                # wan-2-7-pro-edit, flux-2-max-edit,
                                # nano-banana-pro-edit, seedream-v5-lite-edit
    save_path="cat_edited.png",
)
```

`image` accepts: bytes, Path, file path, http(s) URL, data URI, or base64 string. Anything else gets base64-encoded for transport. Endpoint returns raw bytes (NOT JSON).

### Image upscale

```python
image_upscale("output/images/cat.webp", scale=2, save_path="cat_2x.png")
```

Topaz-quality upscale. Scale 2 or 4. ~3 MB result for a 512×512 source at 2x.

### TTS

```python
tts(
    "Welcome to Venice",
    model="tts-kokoro",        # default; alts: tts-xai-v1, tts-elevenlabs-turbo-v2-5,
                                # tts-orpheus, tts-chatterbox-hd, tts-inworld-1-5-max,
                                # tts-qwen3-0-6b, tts-qwen3-1-7b
    voice="af_alloy",          # voice list per model in Venice docs
    response_format="mp3",     # mp3 | opus | aac | flac | wav | pcm
    save_path="welcome.mp3",   # → output/audio/welcome.mp3
)
```

### Transcribe (STT)

```python
result = transcribe(
    "output/audio/welcome.mp3",
    model="openai/whisper-large-v3",  # default. Alt: stt-xai-v1
                                       # The `openai/` prefix is REQUIRED —
                                       # bare `whisper-large-v3` returns 404.
)
print(result["text"])      # transcribed text
print(result["duration"])  # seconds
```

### Embeddings

```python
out = embeddings(["hello world", "second sentence"])
# → {model, count, dim: 1024 (for bge-m3), vectors: list[list[float]], usage}
```

### Characters

```python
list_characters(limit=20)  # [{slug, name, description, tags}, ...]
# Use the slug in chat via venice_parameters['character_slug']
```

## Chat onboarding (BYOK is the answer)

Don't try to wrap chat completions in this skill. The platform has a first-class BYOK flow that handles streaming, history, cost tracking, and model-switcher integration.

**Standard flow when the user says "I want to chat with Venice":**

1. `custom_models(action='templates')` — confirm Venice is in the curated list (it is, with `supports_dynamic_models: true`).
2. Optional but recommended for picky users: `custom_models(action='list_vendor_models', vendor='venice')` — returns the live catalog (~75 text models) with capabilities, pricing, and privacy tier. Filter and present the top picks.
3. `custom_models(action='add_template', vendor='venice', upstream_model='<id>')` — registers Venice with one of Venice's models as the chat target. The `upstream_model` parameter accepts ANY id from step 2's response (Venice has dynamic discovery). Auto-pops the secure-input prompt for the API key.
4. Tell the user how to switch: `/model custom/<id>` in chat, or use the model picker.

**Recommended models (use `list_model_traits()` to keep this fresh):**

| Use case | Trait | Typical pick |
|---|---|---|
| Smartest text | `most_intelligent` | `zai-org-glm-4.7` |
| Uncensored | `most_uncensored` | `venice-uncensored-1-2` |
| Reasoning | `default_reasoning` | `qwen3-235b-a22b-thinking-2507` |
| Vision | `default_vision` | `qwen3-vl-235b-a22b` |
| Code | `default_code` | `qwen3-coder-*` |
| Cheap & fast | `fastest` | `llama-3.2-3b` |
| Function calling | `function_calling_default` | `zai-org-glm-4.7` |
| Privacy: TEE/E2EE | filter `list_models(privacy='tee')` or `'e2ee'` | varies |

Pricing varies wildly: `llama-3.2-3b` is $0.15/$0.60 per 1M tokens; `zai-org-glm-5-1` is $1.75/$5.50; Grok 4.20 is even higher. Always check `list_models()` before recommending if the user is cost-sensitive.

### venice_parameters — Venice-specific chat extensions

Thes