# 向量模型接入

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

## 文本向量（OpenAI SDK）

```python
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` 返回格式。

## 图片、视频与混合输入

```bash
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` 因当前上游账号无访问权限已下架，未将旧名称指向新向量空间。切换模型需要重建已有向量索引。

参见[文本接口](/docs/zh/api/createEmbedding)与[多模态接口](/docs/zh/api/createMultimodalEmbedding)。