agentleFS
0xatd0xatd/cheaptokens-skills/skills/venice-api-overview/SKILL.md

venice-api-overview

Skill2 starsChanged 5 months agoMITView on GitHub

High-level map of the Venice.ai API - base URL, authentication modes, endpoint categories, response headers, pricing model, error shape, and versioning. Load this first when starting any Venice integration.

  • Reads credentials

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    All endpoints live under:

    line 19
  2. Very specific:

    Every inference endpoint accepts either — see venice-auth.

    line 34
  3. Distinctive:

    Every error body follows one of:

    line 104
  4. Very specific:

    Always check the model's model_spec.capabilities from GET /models for feature flags (supportsWebSearch, supportsReasoning, supportsE2EE, …

    line 132
  5. Very specific:

    Read venice-auth and choose Bearer vs x402.

    line 136
  6. Very specific:

    Add error handling using venice-errors (402, 422, 429).

    line 139

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Venice API Overview

Venice.ai is an OpenAI-compatible inference platform for text, image, audio, video, and embeddings. One API — two ways to pay: a traditional API key (Pro account), or a wallet (x402, USDC on Base, no account required).

Use when

  • You're writing code against api.venice.ai for the first time.
  • You need to decide between API-key and x402/wallet authentication.
  • You want a quick map of which endpoint to call for which task.
  • You need to understand the common response headers (X-Balance-Remaining, PAYMENT-REQUIRED, etc.).

Base URL

All endpoints live under:

https://api.venice.ai/api/v1

The OpenAPI spec is distributed at outerface/swagger.yaml (current version 20260420.235001).

Authentication (pick one per request)

SchemeHeaderBest for
BearerAuthAuthorization: Bearer <VENICE_API_KEY>Server-side apps, dashboards, usage analytics, bundled credits
siwx (x402)X-Sign-In-With-X: <base64 SIWE JSON>No account, pay-as-you-go with USDC on Base, serverless / agents

Every inference endpoint accepts either — see venice-auth.

# Bearer
curl https://api.venice.ai/api/v1/models \
  -H "Authorization: Bearer $VENICE_API_KEY"

# x402 / SIWE (one-liner via the SDK)
import { VeniceClient } from 'venice-x402-client'
const v = new VeniceClient(process.env.WALLET_KEY)
await v.models.list()

Endpoint map

Inference

CategoryEndpointsSkill
ChatPOST /chat/completionsvenice-chat
Responses (Alpha)POST /responsesvenice-responses
EmbeddingsPOST /embeddingsvenice-embeddings
Image genPOST /image/generate, POST /images/generations, GET /image/stylesvenice-image-generate
Image editPOST /image/edit, POST /image/multi-edit, POST /image/upscale, POST /image/background-removevenice-image-edit
TTSPOST /audio/speechvenice-audio-speech
STTPOST /audio/transcriptionsvenice-audio-transcription
Music (async)POST /audio/quote, /audio/queue, /audio/retrieve, /audio/completevenice-audio-music
Video (async)POST /video/quote, /video/queue, /video/retrieve, /video/complete, /video/transcriptionsvenice-video

Catalog

CategoryEndpointsSkill
ModelsGET /models, /models/traits, /models/compatibility_mappingvenice-models
CharactersGET /characters, /characters/{slug}, /characters/{slug}/reviewsvenice-characters

Account, billing, wallet

CategoryEndpointsSkill
API keys`GETPOSTDELETE /api_keys, /api_keys/{id}, /api_keys/rate_limits, /api_keys/rate_limits/log, /api_keys/generate_web3_key`venice-api-keys
BillingGET /billing/balance, /billing/usage, /billing/usage-analyticsvenice-billing
x402 walletGET /x402/balance/{wallet}, POST /x402/top-up, GET /x402/transactions/{wallet}venice-x402

Utility

CategoryEndpointsSkill
Crypto RPC proxyGET /crypto/rpc/networks, POST /crypto/rpc/{network}venice-crypto-rpc
AugmentPOST /augment/text-parser, /augment/scrape, /augment/searchvenice-augment

Response headers to watch

HeaderWhenMeaning
X-Balance-Remainingx402 inference successUSDC credits left, e.g. "4.230000"
X-RateLimit-Limit-* / X-RateLimit-Remaining-*all inferenceyour current per-minute/day caps
PAYMENT-REQUIRED402 on x402 inferencebase64 JSON with top-up + SIWX challenge (x402 v2)
Content-Encoding200 when client sent Accept-Encoding: gzip, brcompression (embeddings, chat)

Pricing model at a glance

  • Pricing is dynamic per request, metered in USD.
  • Paid inference endpoints in the spec carry an x-payment-info block with min and max bounds in USD (typically min: 0.001, max: 10.00; higher for bulk video/audio). Read-only discovery routes like GET /models, /models/traits, and /models/compatibility_mapping do not.
  • Pro (Bearer) accounts draw from DIEM (staked credits), USD balance, and bundled credits in priority order.
  • x402 (wallet) users draw from a prepaid USDC credit balance on Base.
  • The authoritative per-model price is on GET /models → model_spec.pricing (when present — video models omit it; use /video/quote for video pricing) (see venice-models).

Standard error shape

Every error body follows one of:

{ "error": "Human-readable message" }

or, for 400 validation errors:

{ "error": "...", "details": { "fieldName": { "_errors": ["Field is required"] } } }

402 on x402 adds structured topUpInstructions and siwxChallenge. See venice-errors for the full table and retry strategy.

OpenAI compatibility — what works and what doesn't

  • Drop-in: /chat/completions, /embeddings, /images/generations, /audio/speech, /audio/transcriptions, /models.
  • Ignored but accepted for compat: user, store.
  • Venice-only extensions live under:
    • venice_parameters (chat completions)
    • venice_parameters is rejected on /responses — use headers / native fields instead
  • Model feature suffixes (e.g. zai-org-glm-5-1:enable_web_search=on, kimi-k2-6:strip_thinking_response=true&disable_thinking=true) flip venice_parameters via the model ID — see venice-chat.

Versioning

  • info.version in swagger.yaml is a timestamp (YYYYMMDD.HHMMSS). There is no /v2; features roll forward on the single /api/v1 surface and are guarded by:
    • Alpha/Beta tags in endpoint descriptions (e.g. /responses, Billing).
    • x-guidance / model capability flags on /models.
  • Always check the model's model_spec.capabilities from GET /models for feature flags (supportsWebSearch, supportsReasoning, supportsE2EE, supportsXSearch, supportsMultipleImages, supportsFunctionCalling, supportsAudioInput, supportsVideoInput, …) before relying on a feature.

Fast start checklist

  1. Read venice-auth and choose Bearer vs x402.
  2. GET /models — pick a model and note its model_spec.constraints and model_spec.pricing.
  3. Wire up one happy-path call from the matching skill.
  4. Add error handling using venice-errors (402, 422, 429).
  5. Hook up observability via X-Balance-Remaining / /billing/usage / /x402/transactions.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.