向量模型接入

当前国内模型为 volcengine/doubao-embedding-vision-251215，兼容别名为 volcengine/doubao-embedding-vision；海外为 volcengine-overseas/skylark-embedding-vision-251215。

文本向量（OpenAI SDK）

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["XRTOKEN_API_KEY"], base_url="https://api.xrtoken.net/v1")
result = client.embeddings.create(
    model="volcengine/doubao-embedding-vision-251215",
    input=["如何查找相似图片", "图片语义检索"],
    dimensions=1024,
    encoding_format="float",
)
print(result.data[0].embedding)
print(result.usage.prompt_tokens)

input 支持一个字符串或最多 128 个字符串；批量输入返回逐条独立向量，data[index] 与输入顺序对应。海外调用需使用 https://api.xrtoken.ai/v1 和海外模型名。支持 float 和 base64 返回格式。

图片、视频与混合输入

curl https://api.xrtoken.net/api/v3/embeddings/multimodal \
  -H "Authorization: Bearer $XRTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "volcengine/doubao-embedding-vision-251215",
    "input": [
      {"type": "text", "text": "一只猫"},
      {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
    ],
    "dimensions": 1024,
    "instructions": "Target_modality: image.\nInstruction:Find an image matching this description.\nQuery:"
  }'

示例图片地址需替换为实际可访问的文件。视频使用 {"type":"video_url","video_url":{"url":"https://example.com/clip.mp4","max_video_tokens":10240}}。支持供应商允许的图片/视频 data URL。网关保留 instructions、sparse_embedding、multi_embedding 等参数，供应商按模型能力校验。

原生多模态接口把内容序列作为一个整体，返回 data.embedding（融合向量）；它与文本兼容接口的 data[] 不同。dimensions 支持 1024 或 2048，默认 2048；稀疏向量只支持纯文本。检索查询和入库内容应根据实际任务配置一致的模型版本、维度和推理提示词。

计费与排查

按实际输入 token 用量计费，不收输出 token 费用；文本和图片/视频 token 单价不同。携带 API Key 请求 GET /v1/models 可查看账号价格：input_per_1m 为文本单价，embedding_visual_input_per_1m 为视觉单价。单价单位为本站币种/百万 token，结算按平台最小货币单位向上取整。

请求前预冻结估算金额，成功后根据 usage.prompt_tokens 和 usage.prompt_tokens_details 结算并释放差额；失败释放冻结。文本兼容批处理会逐条请求上游，任一条失败时整批返回错误、不收取这批费用。视频预冻结默认按模型上下文上限估算；设置有效的 max_video_tokens 可降低预冻结需求。

响应头 X-Request-Id 可用于 GET /v1/credits/requests/{requestId} 查询本次扣费。400 表示输入或模型不匹配；401/403 表示鉴权或权限问题；402 表示余额不足；502 表示上游调用或响应异常。

旧模型 doubao-embedding、doubao-embedding-large 因当前上游账号无访问权限已下架，未将旧名称指向新向量空间。切换模型需要重建已有向量索引。

参见文本接口与多模态接口。