venice-embeddings

name venice-embeddings description Call POST /embeddings on Venice. Covers request shape (input, model, encoding_format, dimensions, user), OpenAI compatibility, response compression (gzip/br), and practical usage for retrieval, clustering, and RAG. Venice Embeddings POST /api/v1/embeddings returns vector embeddings for strings. It's OpenAI-compatible: the request and response match https://api.openai.com/v1/embeddings closely enough that the OpenAI SDK works out of the box with baseURL: "https://api.venice.ai/api/v1" . Use when You're building retrieval / RAG / similarity search. You need text clustering, classification, deduplication, or reranking. You want Venice's "no-training, no-retention" stance on inference inputs — embeddings are generated and returned; the API does not publish E2EE semantics on /embeddings the way it does on selected chat models. Text-only. For image/multimodal signals, either run images through a vision chat model and embed the description, or pick a multimodal-capable embedding model from GET /models?type=embedding (the catalog changes; inspect model_spec on each row). Minimal request curl https://api.venice.ai/api/v1/embeddings \ -H "Authorization: Bearer $VENICE_API_KEY " \ -H "Content-Type: application/json" \ -H "Accept-Encoding: gzip, br" \ -d '{ "model": "text-embedding-bge-m3", "input": "Why is the sky blue?" }' { "object" : "list" , "model" : "text-embedding-bge-m3" , "data" : [ { "object" : "embedding" , "index" : 0 , "embedding" : [ 0.0023 , -0.0093 , 0.0158 , ... ] } ] , "usage" : { "prompt_tokens" : 8 , "total_tokens" : 8 } } Request schema Field Type Notes model string Required. Model ID from GET /models?type=embedding . input string | string[] | number[] | number[][] Required. Single string, array of strings (≤ 2048 entries), or pre-tokenized arrays. encoding_format "float" | "base64" Default "float" . Use "base64" for ~4× payload shrinkage; decode client-side. dimensions integer Optional. Truncate output dimensions. Only meaningful when the model's model_spec.supportsCustomDimensions === true — behavior on non-supporting models is model-dependent; test a small call before relying on it. user string Accepted for OpenAI compat. Discarded by Venice. input max tokens per string is capped at the model's model_spec.maxInputTokens (typically 8192). Batch arrays are capped at 2048 items . Venice returns one embedding per element, in order, with matching index . Response headers & compression Request Accept-Encoding: gzip, br . The response will include Content-Encoding accordingly. For long batches this matters — vectors are large. For x402 auth, X-Balance-Remaining reports your remaining USDC credits. Using the OpenAI SDK import OpenAI from 'openai' const client = new OpenAI ({ apiKey : process. env . VENICE_API_KEY , baseURL : 'https://api.venice.ai/api/v1' , }) const res = await client. embeddings . create ({ model : 'text-embedding-bge-m3' , input : [ 'first doc' , 'second doc' ], }) const vec0 = res. data [ 0 ]. embedding Batch-embedding pattern async function embedBatch ( texts : string [], batchSize = 64 ) { const out : number [][] = [] for ( let i = 0 ; i < texts. length ; i += batchSize) { const slice = texts. slice (i, i + batchSize) const res = await client. embeddings . create ({ model : 'text-embedding-bge-m3' , input : slice, encoding_format : 'float' , }) for ( const row of res. data ) out[i + row. index ] = row. embedding } return out } Keep batches ≤ model context limit total tokens. On 429 , back off exponentially and halve the batch — see venice-errors . Choosing a model Query GET /models?type=embedding for the current catalog. Each entry exposes: model_spec.embeddingDimensions — native output dimension (e.g. 1024 for BGE-M3). model_spec.maxInputTokens — max tokens per input string. model_spec.supportsCustomDimensions — whether dimensions can truncate the output. model_spec.pricing.input.usd / .diem — cost per million input tokens. Built-in options include text-embedding-bge-m3 , text-embedding-bge-en-icl , text-embedding-qwen3-8b , text-embedding-qwen3-0-6b , text-embedding-multilingual-e5-large-instruct , text-embedding-3-small , text-embedding-3-large , gemini-embedding-2-preview , text-embedding-nemotron-embed-vl-1b-v2 . Always pin the model ID — cosine distances are not comparable across different embedding models. Error handling Code Meaning 400 Validation error. Check details in the response for the exact field. 401 Auth / Pro-only model. 402 Insufficient balance. Bearer → INSUFFICIENT_BALANCE . x402 → structured PAYMENT_REQUIRED . 415 Wrong Content-Type — must be application/json . 429 Rate limited. 500 Inference failed; retry with jitter. 503 Model at capacity; retry later. Gotchas dimensions is only meaningful when model_spec.supportsCustomDimensions === true . Behavior on other models is model-dependent — test with a small request before relying on it. input must not be empty; Venice rejects empty strings with 400 . Whether the returned vectors are L2-normalized depends on the model — verify with Math.hypot(...v) ≈ 1 before assuming. For RAG, store model alongside the vector so you can re-embed on upgrade.