生成文本检索向量

把文本批量转换为数值向量，用于自己的相似度检索和索引。

官方资料核对 2026-10-15示例代码，未进行真实接口实测

接入准备

项目密钥可写入 Embeddings；自己准备向量索引或数据库，接口不会自动建立知识库。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行；密钥不应放进公开网页。

OPENAI_API_KEY: 在 API 平台的目标项目中创建的密钥；仅放自己的服务端环境变量。

export OPENAI_API_KEY='replace_with_project_api_key'

以上 export 适用于 macOS / Linux 的终端，在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

01
登录 OpenAI API 平台，创建或选择项目；确认组织、地区资格、模型权限和 API 账单可用。ChatGPT 订阅不代替 API 账单。
02
在目标项目的 API keys 页面创建密钥；若使用受限密钥，授予下方目标端点的写入权限。复制后在自己的服务端设置 OPENAI_API_KEY。
03
本场景把模型改为 text-embedding-3-small；统一数据库向量列的维度，文档和查询端必须使用相同模型与维度。
04
将自己的短文本替换 input，先用小批量建立索引，并保存输入记录与 data[].index 的对应关系。

调用 01

生成 256 维向量

为便于建立较小索引，本例显式使用 dimensions=256；不是模型默认维度。

POSThttps://api.openai.com/v1/embeddings

请求头

Authorization: Bearer ${OPENAI_API_KEY}
Content-Type: application/json

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置	类型 / 必填	说明
`model`请求体	string必填	本例 text-embedding-3-small。
`input`请求体	string[]必填	非空文本数组；每条不超过模型输入上限，不能传空字符串。
`dimensions`请求体	integer可选	本例 256，支持 text-embedding-3 系列；默认维度和可选维度按模型核对。
`encoding_format`请求体	string可选	float 或 base64；本例 float，返回浮点数数组。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

cat > request-body.json <<'JSON'
{
  "model": "text-embedding-3-small",
  "input": [
    "如何接入企业消息通知",
    "如何读取电子表格数据"
  ],
  "dimensions": 256,
  "encoding_format": "float"
}
JSON

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.openai.com/v1/embeddings" \
  --header "Authorization: Bearer ${OPENAI_API_KEY}" \
  --header "Content-Type: application/json" \
  --data-binary @request-body.json

import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://api.openai.com/v1/embeddings")
headers = {
    "Authorization": expand("Bearer ${OPENAI_API_KEY}"),
    "Content-Type": expand("application/json"),
}
body = {
    "model": "text-embedding-3-small",
    "input": [
        "如何接入企业消息通知",
        "如何读取电子表格数据",
    ],
    "dimensions": 256,
    "encoding_format": "float",
}
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(url, data=data, headers=headers, method="POST")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))

// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://api.openai.com/v1/embeddings");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bearer ${OPENAI_API_KEY}",
  "Content-Type": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const body = {
  "model": "text-embedding-3-small",
  "input": [
    "如何接入企业消息通知",
    "如何读取电子表格数据"
  ],
  "dimensions": 256,
  "encoding_format": "float"
};
const response = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方字段整理的响应结构示意，ID、文本和数字均为虚构，非接口实测结果。embedding 数组为展示而截短，仅示出前三个元素；实际本例每条应为 256 维，不能用此示意向量建库。以下为结构示意，非本站实测结果。

{
  "object": "list",
  "model": "text-embedding-3-small",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.012,
        -0.021,
        0.008
      ]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [
        0.019,
        -0.013,
        0.002
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "total_tokens": 18
  }
}

常见错误与排查

HTTP 401密钥认证失败。: 核对环境变量值、项目归属与密钥状态；重新生成已撤销或无效的密钥。
HTTP 403调用身份或所在地区不被允许使用该资源。: 检查模型和项目权限、支持地区及账号验证要求。
HTTP 429请求过快、余额耗尽或组织/项目用量上限触发，原因并不相同。: 读取 error.code；限流按 Retry-After 退避，余额或支出限制需在账单/项目中处理，不能靠快速重试解决。
HTTP 400输入或维度参数不满足模型要求。: 检查非空字符串、Token 长度、批量大小与 dimensions；不要以字符数直接代替 Token 数。

调用注意

官方接口当前要求每条最多 8,192 Token，单请求所有输入合计最多 300,000 Token；批次数量也需符合接口限制。
text-embedding-3-small 默认 1,536 维；本例改成 256 维后，旧索引需重建或使用对应向量列。
返回向量与原文关联、持久化、近邻搜索和权限过滤都由你的应用完成。

Create embeddings 向量维度、用途与按输入 Token 计费 OpenAI HTTP 错误及排查

注意事项

核验日 text-embedding-3-small 标准调用为每百万输入 Token 0.02 美元；向量数据库存储和检索费用另计。
批量输入按输入 Token 用量计费；结果 index 反映原输入顺序，不能只按文本长度匹配。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码，覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

01
OpenAI 官方首次调用与密钥配置核验日期 2026-10-15
02
text-embedding-3-small 模型价格核验日期 2026-10-15
03
OpenAI 组织、项目与模型限流核验日期 2026-10-15
04
Create embeddings核验日期 2026-10-15
05
向量维度、用途与按输入 Token 计费核验日期 2026-10-15
06
OpenAI HTTP 错误及排查核验日期 2026-10-15

OpenAI API的其他调用手册

使用 Responses 生成文本把文字提取成固定 JSON 字段

← 返回OpenAI API的全部功能