venice-embeddings

Venice Embeddings

POST /api/v1/embeddings は文字列のベクトル埋め込みを返します。OpenAI 互換です。リクエストとレスポンスは https://api.openai.com/v1/embeddings と十分に一致しているため、OpenAI SDK は baseURL: "https://api.venice.ai/api/v1" で動作します。ただし例外が 1 つあります。トークン ID の配列は受け付けません（下記を参照）。

認証：Bearer API キーまたは x402 ウォレット（SIGN-IN-WITH-X）— venice-auth を参照してください。

使用する場面

• 検索拡張生成（RAG）や類似検索を構築するとき。
• テキストのクラスタリング、分類、重複排除、再ランキング機能が必要なとき。
• 匿名化されたサードパーティ製モデルではなく、Venice が Private として実行するモデル（カタログの大半）から埋め込みを取得したいとき。各モデルの model_spec.privacy を確認してください。

テキストのみです。input は文字列または文字列の配列である必要があります。画像の場合は、ビジョンチャットモデルで処理して説明文を作成し、その説明文を埋め込んでください。

最小限のリクエスト

curl https://api.venice.ai/api/v1/embeddings \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  --compressed \
  -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 }
}

リクエストのスキーマ

リクエスト本文は 厳密 です（例：input_type、task、truncate などの未知のトップレベルフィールドは 400 で拒否されます）。

フィールド	型	備考
model	string	必須。 GET /models?type=embedding で取得したモデル ID。text-embedding-ada-002 は text-embedding-bge-m3 のエイリアスとして受け付けられます（その場合、レスポンスの model は text-embedding-bge-m3 になります）。
input	string | string[]	必須。 空でない文字列、または 1～2048 個の文字列の配列。トークン ID の配列（number[] / number[][]）は 400 で拒否されます。「注意事項」を参照してください。
encoding_format	"float" | "base64"	デフォルトは "float" です。"base64" を指定すると、各ベクトルが base64 エンコードされた文字列として返されるため、ペイロードを大幅に小さくできます。クライアント側でデコードしてください。
dimensions	integer ≥ 1	省略可能です。要求する出力サイズです。model_spec.supportsCustomDimensions が true のモデルでのみ適用されます。それ以外の場合はそのまま転送され、プロバイダーが無視または拒否する場合があります。
user	string	OpenAI 互換性のために受け付けられます。推論には使用されませんが、値ごとにエラーバジェットが分割されます（venice-errors を参照）。

入力制限

• 項目ごと： Venice はトークン数を ceil(chars / 3.2 × 0.95) で推定し、推定トークン数が 8192 を超える文字列（約 27,500 文字）を 400 "Input text exceeds the maximum token limit of 8192 tokens" で拒否します。この上限は、maxInputTokens が 32768 のモデルを含む、すべてのモデルで共通です。
• モデルの上限： model_spec.maxInputTokens がより小さいモデル（例：text-embedding-multilingual-e5-large-instruct の 512、gemini-embedding-2-preview の 2048）は、その上限を独自に適用します。Venice の事前チェックでは適用されません。モデルの maxInputTokens に合わせて分割してください。
• バッチ： 1 リクエストあたり最大 2048 個の文字列を指定できます。Venice は各要素に対して 1 つずつ、入力順に対応する index とともに埋め込みを返します。

レスポンスヘッダーと圧縮

Accept-Encoding: gzip, br を送信してください（curl の場合は --compressed。ほとんどの HTTP クライアントは自動的にデコードします）。レスポンスには Content-Encoding が設定されます。大きなバッチでは重要です。JSON の浮動小数点ベクトルはサイズが大きいためです。

次のヘッダーも返されます。

• x-ratelimit-limit-* / x-ratelimit-remaining-* / x-ratelimit-reset-*（requests、tokens）— venice-errors を参照してください。
• x-venice-balance-usd / x-venice-balance-diem — 残高がゼロでない場合の現在の残高です。
• X-Balance-Remaining — x402 呼び出し元向けの仕様には記載されていますが、現在サーバーからは設定されません。代わりに GET /x402/balance/{walletAddress} をポーリングしてください。

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

OpenAI Node SDK は、encoding_format を省略すると base64 を要求し、クライアント側でデコードします。Venice は encoding_format をモデルに転送します。デコードされたベクトルが正しく見えない場合は、encoding_format: 'float' を明示的に指定してください。

LangChain

LangChain の OpenAIEmbeddings はデフォルトで入力をトークン化してトークン配列を送信しますが、Venice はこれを拒否します。無効にしてください：

import os
from langchain_openai import OpenAIEmbeddings

emb = OpenAIEmbeddings(
    model="text-embedding-bge-m3",
    base_url="https://api.venice.ai/api/v1",
    api_key=os.environ["VENICE_API_KEY"],
    check_embedding_ctx_length=False,
)

このフラグを指定せずに内部で OpenAIEmbeddings を構築するラッパー（gpt-researcher の openai プロバイダーなど）でも、同じ 400 エラーが発生します。

バッチ埋め込みのパターン

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
}

• 各文字列を上記の項目ごとの制限以内に収めてください。バッチサイズの上限は2048です。
• 429 が発生したら、指数バックオフを行い、バッチサイズを半分にしてください。詳細は venice-errors を参照してください。

モデルの選択

GET /models?type=embedding をクエリして、最新のカタログを確認してください。各エントリの model_spec には、以下の情報が含まれています：

• embeddingDimensions — ネイティブ出力の次元数（例：text-embedding-bge-m3 は1024、text-embedding-qwen3-8b は4096）。
• maxInputTokens — モデルごとの入力トークン上限。
• supportsCustomDimensions — dimensions に対応するモデルに限り、true として存在します（それ以外のモデルにはありません）。
• privacy — "private"（データを保持しない）または "anonymized"（サードパーティのモデル。リクエストはお客様の身元情報なしで送信されます）。
• pricing.input / pricing.output — 100万トークンあたりの { usd, diem }。

代表的な ID：text-embedding-bge-m3（private、1024次元）、text-embedding-qwen3-8b（private、4096次元、カスタム次元に対応）、text-embedding-multilingual-e5-large-instruct（入力上限512トークン）、text-embedding-3-small / text-embedding-3-large（anonymized、OpenAI、カスタム次元に対応）、gemini-embedding-2-preview（anonymized、カスタム次元に対応）。リストは変更されるため、必ず /models から取得してください。

モデル ID は必ず固定してください。異なる埋め込みモデル間では、コサイン距離を比較できません。

エラー処理

コード	意味
400	model がない、または検証エラー（details にフィールド名が記載されます）：トークン配列の入力、空の文字列／配列、2048項目超過、8192トークンの推定上限を超える項目、不明なフィールド。JSON 以外の Content-Type → "'Content-Type' must be 'application/json'"。モデル側での拒否（入力がモデル固有の上限を超えている場合など）も含まれます。抽出できる場合はモデルからのメッセージを返し、それ以外の場合は一般的な "Invalid request parameters…" を返します。
401	API キーまたは SIWX 署名が無効です。
402	残高不足、またはキーの USD／DIEM 使用上限に達しています。Bearer → "Insufficient USD or Diem balance…"、x402 → 支払い要求の本文と PAYMENT-REQUIRED ヘッダーが返されます。認証情報がまったくないリクエストも 401 ではなく 402（x402 の検出チャレンジ）になります。
403	API キーの modelPrivacy が PRIVATE_TEXT または PRIVATE_ONLY で、モデルが anonymized の場合です。リージョン／プロバイダーの制限や、アカウントで API アクセスが無効になっている場合も該当します。
404	不明なモデルです（メッセージに類似するモデルが提示される場合があります）。
429	レート制限です。
500	推論に失敗しました。ジッターを加えて再試行してください。
503	モデルが一時的にオフラインです。後で再試行してください。

注意点

• トークン配列は拒否されます。 input: [101, 2023, ...] または [[101, ...]] を送信すると、400 "Token array inputs are not supported. Pass a string or an array of strings." が返されます。テキストを送信してください。
• 埋め込みにも API キーのプライバシー設定が適用されます。 modelPrivacy: PRIVATE_TEXT（または PRIVATE_ONLY）のキーで呼び出せるのは、private の埋め込みモデルのみです。text-embedding-3-* と gemini-embedding-2-preview は 403 を返します。詳細は venice-api-keys を参照してください。
• トップレベルの空文字列は 400 で拒否されますが、配列内の空文字列は事前に検査されません。自分で除外してください。
• リクエストの Content-Type は application/json である必要があります。それ以外は認証や検証の前に 400 "'Content-Type' must be 'application/json'" で拒否されます。
• 返されるベクトルが L2 正規化されているかどうかはモデルによって異なります。正規化されていると仮定する前に、Math.hypot(...v) ≈ 1 で確認してください。
• RAG では、アップグレード時に再埋め込みできるよう、各ベクトルとともに model（および設定されている場合は dimensions）を保存してください。