功能简介
NewAPI 是一款大模型 API 接口管理与分发工具，可以将 大模型厂商 或 自部署大模型 提供的 API 接口一键封装成 统一的、标准的 OpenAI API 接口格式，从而实现使用统一接口访问所有大模型服务。
安装部署
单机部署
使用 SQLite
适合测试环境。
适合个人、小规模、低并发场景。
# 环境需求
Docker-Compose_v2.0+
# 准备文件夹
sudo mkdir -p ./LLM/New-API/new-api
sudo mkdir -p ./LLM/New-API/logs# ./LLM/New-API/docker-compose-llm-new-api.yml 文件如下
version: '3.1'
services:
llm-new-api:
image: calciumion/new-api:v0.9.10-amd64
container_name: LLM-NewAPI
restart: always
ports:
- "13416:3000"
privileged: true
volumes:
# 数据文件夹
- ./new-api:/data
# 日志文件夹
- ./logs:/app/logs
environment:
# 更多可用环境变量，参考【环境变量】一节
# 设置时区
- TZ=Asia/Shanghai
# 使用固定的会话密钥（系统重新启动后已登录用户的 cookie 将依旧有效）
- SESSION_SECRET=PVhkjrozbQxuwwrVwMpw
# 在前端显示错误日志
- ERROR_LOG_ENABLED=true
# 启用批量更新
- BATCH_UPDATE_ENABLED=true
command: --log-dir /app/logs
# 修改容器内默认的端口号（将默认 3000 修改为 8000，注意 ports: 部分和 healthcheck: 部分也需做同步更改）
# command: --log-dir /app/logs --port 8000
healthcheck:
test: [ "CMD-SHELL", "wget -q -O - http://localhost:3000/api/status | grep -o '\"success\":\\s*true' || exit 1"]
interval: 30s
timeout: 10s
retries: 3# 一键启动
sudo docker-compose -f docker-compose-llm-new-api.yml up -d
# 初始化启动会有些慢，请耐心等待...
# 使用 sudo docker ps -a 命令查看容器状态变为 (healthy) 即可使用 MySQL + Redis
适合生产环境。
适合团队、大规模、高并发场景。
# 环境需求
Docker-Compose_v2.0+
# 准备文件夹
sudo mkdir -p ./LLM/New-API/new-api
sudo mkdir -p ./LLM/New-API/logs
sudo mkdir -p ./LLM/New-API/mysql# ./LLM/New-API/docker-compose-llm-new-api.yml 文件如下
version: '3.1'
services:
llm-new-api:
image: calciumion/new-api:v0.9.10-amd64
container_name: LLM-NewAPI
restart: always
ports:
- "13416:3000"
privileged: true
volumes:
# 数据文件夹
- ./new-api:/data
# 日志文件夹
- ./logs:/app/logs
environment:
# 更多可用环境变量，参考【环境变量】一节
# 设置时区
- TZ=Asia/Shanghai
# 使用固定的会话密钥（系统重新启动后已登录用户的 cookie 将依旧有效）
- SESSION_SECRET=PVhkjrozbQxuwwrVwMpw
# 在前端显示错误日志
- ERROR_LOG_ENABLED=true
# 启用批量更新
- BATCH_UPDATE_ENABLED=true
# 使用 MySQL 数据库
# - SQL_DSN=newapi:mnIirsCiEJYc@tcp(llm-new-api-db:3306)/new-api
- SQL_DSN=root:RvEiNpbYlUZs@tcp(llm-new-api-db:3306)/new-api
# 使用 Redis
- REDIS_CONN_STRING=redis://llm-new-api-redis:6379
depends_on:
- llm-new-api-db
- llm-new-api-redis
networks:
- llm-new-api-network
command: --log-dir /app/logs
# 修改容器内默认的端口号（将默认 3000 修改为 8000，注意 ports: 部分和 healthcheck: 部分也需做同步更改 ）
# command: --log-dir /app/logs --port 8000
healthcheck:
test: [ "CMD-SHELL", "wget -q -O - http://localhost:3000/api/status | grep -o '\"success\":\\s*true' || exit 1"]
interval: 30s
timeout: 10s
retries: 3
llm-new-api-db:
image: mysql:8.2.0
container_name: LLM-NewAPI-MySQL
restart: always
ports:
- "13417:3306"
privileged: true
volumes:
- ./mysql:/var/lib/mysql
environment:
# 设置时区
TZ: Asia/Shanghai
# 设置 root 用户的密码
MYSQL_ROOT_PASSWORD: 'RvEiNpbYlUZs'
# 创建专用用户
MYSQL_USER: newapi
# 设置专用用户密码
MYSQL_PASSWORD: 'mnIirsCiEJYc'
# 自动创建数据库
MYSQL_DATABASE: new-api
networks:
- llm-new-api-network
llm-new-api-redis:
image: redis:latest
container_name: LLM-NewAPI-Redis
restart: always
networks:
- llm-new-api-network
networks:
llm-new-api-network:
driver: bridge# 一键启动
sudo docker-compose -f docker-compose-llm-new-api.yml up -d
# 初始化启动会有些慢，请耐心等待...
# 使用 sudo docker ps -a 命令查看容器状态，期间会重启数次，直到变为 (healthy) 即可集群部署
前置要求
已有多台服务器：至少 2 台，一主多从 架构
已安装 Docker_v20+ 和 Docker-Compose_v2.0+
已安装共享的 MySQL 数据库：主从节点需访问同一数据库
已安装共享的 Redis 服务：用于节点间数据同步和缓存
（可选）已安装负载均衡器：推荐 Nginx
集群架构图
New API 集群采用主从架构设计：
主节点：负责处理所有写操作和部分读操作
从节点：主要负责处理读操作，提高系统整体吞吐量
集群部署关键配置
集群部署的关键在于所有节点必须：
共享相同的数据库：所有节点访问同一 MySQL 数据库
共享相同的 Redis：用于缓存和节点间通信
使用相同的密钥：
SESSION_SECRET和CRYPTO_SECRET必须在所有节点上相同正确配置节点类型：主节点为
master，从节点为slave
部署步骤
（Step01）部署共享 MySQL 和 Redis
对于 MySQL 数据库，可以选择以下架构方案：
无论选择哪种架构，应用程序的
SQL_DSN配置都只需要一个统一入口地址。
确保这些服务能够被所有节点访问，并具有足够的性能和可靠性。
（Step02）配置主节点
以下操作均在 主节点 服务器上进行
# 环境需求
Docker-Compose_v2.0+
# 准备文件夹
sudo mkdir -p ./LLM/New-API/new-api-master
sudo mkdir -p ./LLM/New-API/logs-master# ./LLM/New-API/docker-compose-llm-new-api-master.yml 文件如下
version: '3.1'
services:
llm-new-api-master:
image: calciumion/new-api:v0.9.10-amd64
container_name: LLM-NewAPI-Master
restart: always
ports:
- "13416:3000"
privileged: true
volumes:
# 数据文件夹
- ./new-api-master:/data
# 日志文件夹
- ./logs-master:/app/logs
environment:
# 更多可用环境变量，参考【环境变量】一节
# 设置时区
- TZ=Asia/Shanghai
# 会话密钥（多机部署必须）
- SESSION_SECRET=your-unique-session-secret
# 加密密钥（加密数据库内容）
- CRYPTO_SECRET=your-unique-crypto-secret
# 使用 MySQL 数据库
- SQL_DSN=your-db-user:your-db-password@tcp(your-db-host:your-db-port)/your-db-database-such-as-new-api
# 对于大规模集群，建议使用独立的日志数据库，进行集中式日志管理系统
# - LOG_SQL_DSN=your-db-user:your-db-password@tcp(your-db-host:your-db-port)/your-db-database-such-as-new-api-logs
# 使用 Redis
- REDIS_CONN_STRING=redis://default:your-redis-password@your-redis-host:your-redis-port
# Redis 集群或哨兵模式
# - REDIS_CONN_STRING=redis://your-redis-host:your-redis-port
# - REDIS_PASSWORD=your-redis-password
# 哨兵模式下的主节点名称
# - REDIS_MASTER_NAME=mymaster
# Redis 连接池大小
# - REDIS_CONN_POOL_SIZE=10
# 以下是可选配置
# 从节点与主节点同步频率（秒）
- SYNC_FREQUENCY=60
# 启用批量更新
- BATCH_UPDATE_ENABLED=true
# 批量更新间隔（秒）
- BATCH_UPDATE_INTERVAL=5
# 前端界面 URL，用于邮件通知等功能
- FRONTEND_BASE_URL=https://your-domain.com
command: --log-dir /app/logs
# 修改容器内默认的端口号（将默认 3000 修改为 8000，注意 ports: 部分和 healthcheck: 部分也需做同步更改）
# command: --log-dir /app/logs --port 8000
healthcheck:
test: [ "CMD-SHELL", "wget -q -O - http://localhost:3000/api/status | grep -o '\"success\":\\s*true' || exit 1"]
interval: 30s
timeout: 10s
retries: 3# 一键启动主节点
sudo docker-compose -f docker-compose-llm-new-api-master.yml up -d
# 初始化启动会有些慢，请耐心等待...
# 使用 sudo docker ps -a 命令查看容器状态变为 (healthy) 即可（Step03）配置从节点
以下操作均在 从节点 服务器上进行
对 每台 从节点 服务器重复相同步骤
# 环境需求
Docker-Compose_v2.0+
# 准备文件夹
sudo mkdir -p ./LLM/New-API/new-api-slave
sudo mkdir -p ./LLM/New-API/logs-slave# ./LLM/New-API/docker-compose-llm-new-api-slave.yml 文件如下
version: '3.1'
services:
llm-new-api-slave:
image: calciumion/new-api:v0.9.10-amd64
container_name: LLM-NewAPI-Slave
restart: always
ports:
# 如果主从节点在不同服务器上，则可与主节点使用相同端口
# 否则请自定义端口，避免与主节点冲突
- "13416:3000"
privileged: true
volumes:
# 数据文件夹
- ./new-api-slave:/data
# 日志文件夹
- ./logs-slave:/app/logs
environment:
# 更多可用环境变量，参考【环境变量】一节
# 指定为从节点（关键配置）
- NODE_TYPE=slave
# 设置时区
- TZ=Asia/Shanghai
# 会话密钥（多机部署必须）（必须与主节点相同）
- SESSION_SECRET=your-unique-session-secret
# 加密密钥（加密数据库内容）（必须与主节点相同）
- CRYPTO_SECRET=your-unique-crypto-secret
# 使用 MySQL 数据库（必须与主节点相同）
- SQL_DSN=your-db-user:your-db-password@tcp(your-db-host:your-db-port)/your-db-database-such-as-new-api
# 对于大规模集群，建议使用独立的日志数据库，进行集中式日志管理系统
# - LOG_SQL_DSN=your-db-user:your-db-password@tcp(your-db-host:your-db-port)/your-db-database-such-as-new-api-logs
# 使用 Redis（必须与主节点相同）
- REDIS_CONN_STRING=redis://default:your-redis-password@your-redis-host:your-redis-port
# Redis 集群或哨兵模式
# - REDIS_CONN_STRING=redis://your-redis-host:your-redis-port
# - REDIS_PASSWORD=your-redis-password
# 哨兵模式下的主节点名称
# - REDIS_MASTER_NAME=mymaster
# Redis 连接池大小
# - REDIS_CONN_POOL_SIZE=10
# 从节点与主节点同步频率（秒）（必须与主节点相同）
- SYNC_FREQUENCY=60
# 启用批量更新（必须与主节点相同）
- BATCH_UPDATE_ENABLED=true
# 批量更新间隔（秒）（必须与主节点相同）
- BATCH_UPDATE_INTERVAL=5
# 以下是可选配置
# 前端界面 URL，用于邮件通知等功能（必须与主节点相同）
- FRONTEND_BASE_URL=https://your-domain.com
command: --log-dir /app/logs
# 修改容器内默认的端口号（将默认 3000 修改为 8000，注意 ports: 部分和 healthcheck: 部分也需做同步更改）
# command: --log-dir /app/logs --port 8000
healthcheck:
test: [ "CMD-SHELL", "wget -q -O - http://localhost:3000/api/status | grep -o '\"success\":\\s*true' || exit 1"]
interval: 30s
timeout: 10s
retries: 3# 一键启动从节点
sudo docker-compose -f docker-compose-llm-new-api-slave.yml up -d
# 初始化启动会有些慢，请耐心等待...
# 使用 sudo docker ps -a 命令查看容器状态变为 (healthy) 即可（Step04）配置负载均衡
为了实现流量的均衡分配，需要设置负载均衡器。
以下示例使用 Nginx 作为负载均衡器
upstream new_api_cluster {
# 将主节点权重设置为 3
# 从节点权重设置为 5
# 意味着从节点将处理更多的请求
# 根据实际需求自行调节这些权重
server master-node-ip:3000 weight=3;
server slave-node1-ip:3000 weight=5;
server slave-node2-ip:3000 weight=5;
# 可添加更多从节点
}
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://new_api_cluster;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}（可选）扩容
随着业务增长，如需扩展集群规模，可按照如下步骤操作：
准备新服务器：已安装 Docker_v20+ 和 Docker-Compose_v2.0+
配置从节点：参照【（Step03）配置从节点】来配置新的从节点
更新负载均衡器配置：将新节点添加到负载均衡器配置中
测试新节点：确保新节点能正常工作并参与负载均衡
环境变量
基本配置
数据库配置
缓存配置
多节点与安全配置
用户及令牌配置
请求限制配置
设置
RELAY_TIMEOUT环境变量时请谨慎，如果设置过短可能导致以下问题：
上游 API 已经完成请求并计费，但本地因超时而未完成计费
造成计费不同步，可能导致系统亏损
建议保持默认值
渠道管理配置
模型和请求处理配置
Tiktoken 是 OpenAI 使用的分词器，用于计算文本的 token 数量。通过本地缓存这些文件，可以避免系统每次启动时从网络下载，提高稳定性和性能，特别是在网络受限环境中。
下载 Tiktoken 文件后，请按照以下方式重命名：
cl100k_base.tiktoken重命名为9b5ad71b2ce5302211f9c61530b329a4922fc6a4
o200k_base.tiktoken重命名为fb374d419588a4632f3f557e76b4b70aebbca790这些文件应放置在
TIKTOKEN_CACHE_DIR指定的目录中，以提高 token 计算性能并减少网络依赖。Tiktoken配置示例
# Docker 环境示例 TIKTOKEN_CACHE_DIR=/app/data/tiktoken # 然后将 tiktoken 文件下载并重命名后放入该目录： /app/data/tiktoken/9b5ad71b2ce5302211f9c61530b329a4922fc6a4 /app/data/tiktoken/fb374d419588a4632f3f557e76b4b70aebbca790
特定模型配置
其他配置
系统使用
系统访问
# 首先确保服务器防火墙已开放 13416 端口
# 首次启动会进入初始化页面，跟随指引操作即可
http://服务器IP:13416系统设置
渠道管理
用来管理和添加大模型渠道供应商的大模型服务，只有超级管理员才能设置。
选择某渠道后（如阿里通义千问），模型配置 - 模型显示框中所显示的模型，是系统内置的该渠道一般会有的模型，并非该渠道最新的、准确的模型列表（因为随着时间渠道可能会有新增、删除等模型变动，这些时效性信息无法与系统内置信息同步）。
获取模型列表：获取该渠道最新的、准确的模型列表。如果 获取模型列表 失败，未必是 网络 或 你填入的密钥 有问题，可能是你当前所选渠道未提供标准的模型列表查询接口。
自定义模型名称：如果 获取模型列表 失败，或已知该渠道有 xxx 模型（可前往模型渠道供应商的官网查看获取），可在 自定义模型名称 中手动填写，然后点击 填入 添加到当前模型列表中。
模型重定向：为该渠道的某些模型改名（键为对外提供的改名后的模型名，值为该渠道原始模型名），用于区分不同模型渠道供应商可能会有相同的模型名。
分组：一共 default, vip, svip 三组（对应用户组），用来限制该渠道中的模型可供哪个级别的用户组调用。如 svip 用户可使用所有渠道（default, vip, svip）的模型，vip 用户可使用（default, vip）渠道的模型。
令牌管理
每个用户都可以设置自己的专属令牌，供客户端或调用方使用，等同于大模型厂商提供的【密钥】。
在令牌中可自定义选择限制该令牌可用模型列表（总模型列表取决于该用户能访问的模型列表）。
兑换码管理
管理兑换码，类似话费充值卡。
钱包管理
给账户充值，与兑换码搭配使用。
输入一个有效兑换码，就相当于给当前账户充值对应的额度，供令牌调用消耗。
系统调用
当【令牌】设置完毕，即可使用令牌访问调用大模型服务了，使用方式与标准的 OpenAI API 一致。
# API_BASE_URL="http://<ip>:<port>/v1"
# API_KEY="你的令牌"
API_BASE_URL="http://www.jusdot.cn:13416/v1"
API_KEY="sk-xxxxxx"
# 可以通过在令牌后面添加渠道 ID 的方式指定使用哪一个渠道处理本次请求，如：
Authorization: Bearer API_KEY-CHANNEL_ID
# 必须是管理员用户创建的令牌才能指定渠道 ID
# 不指定的话将会使用负载均衡的方式使用多个渠道用户可用模型列表
接口描述
获取当前用户可用模型列表
（用户可用权限由：用户管理 - 用户分组 default、vip、svip 决定）
请求说明
（1）HTTP 方法：GET
（2）请求 URL： http://<your-domain>/api/user/models
（3）请求头
返回说明
（1）返回结果
（2）返回示例
{
"success":true,
"message":"",
"data":[
"deepseek-r1",
"deepseek-v3.1",
"qwen3-max",
"qwen3-vl-plus"
]
}接口访问
# 使用 curl
curl -X GET "http://<your-domain>/api/user/models" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <USER_TOKEN>" \
-H "New-Api-User: <USER_ID>"令牌可用模型列表
接口描述
获取当前令牌可用模型列表
（令牌可用权限由：令牌管理 - 模型限制列表 决定）
请求说明
（1）HTTP 方法：GET
（2）请求 URL： http://<your-domain>/v1/models
（3）请求头
返回说明
（1）返回结果
（2）返回示例
{
"success":true,
"object":"list",
"data":[
{"id":"deepseek-chat",
"object":"model",
"created":1626777600,
"owned_by":"deepseek",
"supported_endpoint_types":["openai"]
},
{"id":"deepseek-reasoner",
"object":"model",
"created":1626777600,
"owned_by":"deepseek",
"supported_endpoint_types":["openai"]
}
]
}接口访问
# 使用 curl
curl -X GET "http://<your-domain>/v1/models" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API_KEY>"OpenAI 对话格式（Chat Completions）
给定一组包含对话的消息列表，模型将返回一个响应。
基础文本对话
curl https://<your-domain>/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API_KEY>" \
-d '{
"model": "gpt-4.1",
"messages": [
{
"role": "developer",
"content": "你是一个有帮助的助手。"
},
{
"role": "user",
"content": "你好！"
}
]
}'响应示例：
{
"id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
"object": "chat.completion",
"created": 1741569952,
"model": "gpt-4.1-2025-04-14",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "你好！我能为你提供什么帮助？",
"refusal": null,
"annotations": []
},
"logprobs": null,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 19,
"completion_tokens": 10,
"total_tokens": 29,
"prompt_tokens_details": {
"cached_tokens": 0,
"audio_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"service_tier": "default"
}流式响应
curl https://<your-domain>/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API_KEY>" \
-d '{
"model": "gpt-4.1",
"messages": [
{
"role": "developer",
"content": "你是一个有帮助的助手。"
},
{
"role": "user",
"content": "你好！"
}
],
"stream": true
}'响应示例：
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"你好"},"logprobs":null,"finish_reason":null}]}
// ... 更多数据块 ...
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}图像分析对话
curl https://<your-domain>/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API_KEY>" \
-d '{
"model": "gpt-4.1",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "这张图片里有什么？"
},
{
"type": "image_url",
"image_url": {
"url": "https://images.jpg"
}
}
]
}
],
"max_tokens": 300
}'响应示例：
{
"id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
"object": "chat.completion",
"created": 1741570283,
"model": "gpt-4.1-2025-04-14",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "图片展示了一条穿过茂密绿色草地或草甸的木制栈道。天空湛蓝，点缀着几朵散落的云彩，给整个场景营造出宁静祥和的氛围。背景中可以看到树木和灌木丛。",
"refusal": null,
"annotations": []
},
"logprobs": null,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 1117,
"completion_tokens": 46,
"total_tokens": 1163,
"prompt_tokens_details": {
"cached_tokens": 0,
"audio_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"service_tier": "default",
"system_fingerprint": "fp_fc9f1d7035"
}函数调用
curl https://<your-domain>/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API_KEY>" \
-d '{
"model": "gpt-4.1",
"messages": [
{
"role": "user",
"content": "波士顿今天的天气怎么样？"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "获取指定位置的当前天气",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市和州，例如 San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location"]
}
}
}
],
"tool_choice": "auto"
}'响应示例：
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1699896916,
"model": "gpt-4o-mini",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "get_current_weather",
"arguments": "{\n\"location\": \"Boston, MA\"\n}"
}
}
]
},
"logprobs": null,
"finish_reason": "tool_calls"
}
],
"usage": {
"prompt_tokens": 82,
"completion_tokens": 17,
"total_tokens": 99,
"completion_tokens_details": {
"reasoning_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
}
}OpenAI 响应格式（Responses）
OpenAI 最先进的模型响应接口。支持文本和图像输入，以及文本输出。创建与模型的有状态交互，将先前响应的输出用作输入。通过文件搜索、网络搜索、计算机使用等内置工具扩展模型的能力。使用函数调用允许模型访问外部系统和数据。
基础文本响应
curl https://<your-domain>/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API_KEY>" \
-d '{
"model": "gpt-4.1",
"input": "讲一个三句话的关于独角兽的睡前故事。"
}'响应示例：
{
"id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
"object": "response",
"created_at": 1741476542,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "message",
"id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "在一个宁静的月夜下，一只名叫璐米娜的独角兽发现了一个倒映着星星的隐藏水池。当她将独角浸入水中时，水池开始闪烁，显现出通往一个有着无尽夜空的魔法世界的路径。充满好奇，璐米娜为所有做梦的人许下愿望，希望他们能找到自己的隐藏魔法，当她回头望去，她的蹄印像星尘一样闪烁。",
"annotations": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 36,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 87,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 123
},
"user": null,
"metadata": {}
}流式响应
curl https://<your-domain>/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API_KEY>" \
-d '{
"model": "gpt-4.1",
"instructions": "你是一个有帮助的助手。",
"input": "你好！",
"stream": true
}'响应示例：
event: response.created
data: {"type":"response.created","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"你是一个有帮助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}}
event: response.in_progress
data: {"type":"response.in_progress","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"你是一个有帮助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}}
event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]}}
event: response.content_part.added
data: {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"你好"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"！"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":" 我"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"能"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"为"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"您"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"提供"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"什么"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"帮助"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"吗"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"？"}
event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"text":"你好！ 我能为您提供什么帮助吗？"}
event: response.content_part.done
data: {"type":"response.content_part.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"你好！ 我能为您提供什么帮助吗？","annotations":[]}}
event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"你好！ 我能为您提供什么帮助吗？","annotations":[]}]}}
event: response.completed
data: {"type":"response.completed","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"completed","error":null,"incomplete_details":null,"instructions":"你是一个有帮助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"你好！ 我能为您提供什么帮助吗？","annotations":[]}]}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":37,"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":48},"user":null,"metadata":{}}}图像分析响应
curl https://<your-domain>/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API_KEY>" \
-d '{
"model": "gpt-4.1",
"input": [
{
"role": "user",
"content": [
{"type": "input_text", "text": "描述这张图片中的内容"},
{
"type": "input_image",
"image_url": "https://images.jpg"
}
]
}
]
}'响应示例：
{
"id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41",
"object": "response",
"created_at": 1741476777,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "message",
"id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "这张图片展示了一条木制栈道或小径穿过茂密的绿色草地，上方是点缀着几朵云的蓝天。场景呈现出一个宁静的自然区域，可能是公园或自然保护区。背景中有树木和灌木丛。整个景观展现出和谐的自然环境，栈道为游客提供了一条穿过湿地或草原而不影响周围生态系统的路径。",
"annotations": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 328,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 52,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 380
},
"user": null,
"metadata": {}
}网络搜索工具
curl https://<your-domain>/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API_KEY>" \
-d '{
"model": "gpt-4.1",
"tools": [{ "type": "web_search_preview" }],
"input": "今天有什么积极正面的新闻?"
}'响应示例：
{
"id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c",
"object": "response",
"created_at": 1741484430,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "web_search_call",
"id": "ws_67ccf18f64008190a39b619f4c8455ef087bb177ab789d5c",
"status": "completed"
},
{
"type": "message",
"id": "msg_67ccf190ca3881909d433c50b1f6357e087bb177ab789d5c",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "截至今天，2025年3月9日，一则值得关注的积极新闻是中国科学家在可再生能源领域取得重大突破，成功研发出一种新型高效太阳能电池，转化率达到了创纪录的35%，这可能会极大推动清洁能源的普及和应用。这项技术预计将使太阳能发电成本降低约40%，为全球减少碳排放提供了新的解决方案。",
"annotations": [
{
"type": "url_citation",
"start_index": 42,
"end_index": 100,
"url": "https://example.com/renewable-energy-breakthrough/?utm_source=chatgpt.com",
"title": "中国科学家在可再生能源领域取得重大突破"
},
{
"type": "url_citation",
"start_index": 101,
"end_index": 150,
"url": "https://example.com/solar-cell-efficiency-record/?utm_source=chatgpt.com",
"title": "新型高效太阳能电池转化率创纪录"
},
{
"type": "url_citation",
"start_index": 151,
"end_index": 200,
"url": "https://example.com/clean-energy-cost-reduction/?utm_source=chatgpt.com",
"title": "太阳能发电成本有望降低40%"
}
]
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "web_search_preview",
"domains": [],
"search_context_size": "medium",
"user_location": {
"type": "approximate",
"city": null,
"country": "US",
"region": null,
"timezone": null
}
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 328,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 356,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 684
},
"user": null,
"metadata": {}
}文件搜索工具
curl https://<your-domain>/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API_KEY>" \
-d '{
"model": "gpt-4.1",
"tools": [{
"type": "file_search",
"vector_store_ids": ["vs_1234567890"],
"max_num_results": 20
}],
"input": "古代棕龙有哪些特性和属性?"
}'响应示例：
{
"id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7",
"object": "response",
"created_at": 1741485253,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "file_search_call",
"id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7",
"status": "completed",
"queries": [
"古代棕龙的特性和属性"
],
"results": null
},
{
"type": "message",
"id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "根据资料，古代棕龙具有以下特性和属性：\n\n1. 物理特征：古代棕龙体型庞大，体长可达25-30米，翼展约35米。它们的鳞片呈深棕色至铜色，随着年龄增长会变得更加暗沉。头部有特征性的双角和脊刺，下颚强壮，适合撕裂猎物。\n\n2. 能力：它们能喷吐强力的酸液，对目标造成严重腐蚀伤害。古代棕龙还拥有出色的掘地能力，常在沙漠或山地挖掘复杂的巢穴系统。\n\n3. 智力：被认为是龙族中最为狡猾和有耐心的品种，智力极高，精通多种语言，并具有复杂的战术思维。\n\n4. 栖息地：主要栖息在干旱的山地和沙漠地区，喜欢炎热干燥的环境。\n\n5. 宝藏：古代棕龙以其庞大的宝藏闻名，特别喜爱收集铜币、红宝石和火焰魔法物品。\n\n6. 寿命：是所有龙种中寿命最长的之一，可活2000-2500年，随着年龄增长其力量和魔法能力也会增强。\n\n7. 性格：极度领地意识强，性格暴躁易怒，对侵入者毫不留情，但也以其罕见的耐心著称，能为复仇等待几个世纪。",
"annotations": [
{
"type": "file_citation",
"index": 80,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 233,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 345,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 420,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 520,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 580,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 655,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 781,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
}
]
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "file_search",
"filters": null,
"max_num_results": 20,
"ranking_options": {
"ranker": "auto",
"score_threshold": 0.0
},
"vector_store_ids": [
"vs_1234567890"
]
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 18307,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 348,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 18655
},
"user": null,
"metadata": {}
}函数调用
curl https://<your-domain>/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API_KEY>" \
-d '{
"model": "gpt-4.1",
"input": "波士顿今天的天气如何？",
"tools": [
{
"type": "function",
"name": "get_current_weather",
"description": "获取指定位置的当前天气",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市和州，例如 San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location", "unit"]
}
}
],
"tool_choice": "auto"
}'响应示例：
{
"id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0",
"object": "response",
"created_at": 1741294021,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1-2025-04-14",
"output": [
{
"type": "function_call",
"id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0",
"call_id": "call_unLAR8MvFNptuiZK6K6HCy5k",
"name": "get_current_weather",
"arguments": "{\"location\":\"波士顿, MA\",\"unit\":\"celsius\"}",
"status": "completed"
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "function",
"description": "获取指定位置的当前天气",
"name": "get_current_weather",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市和州，例如 San Francisco, CA"
},
"unit": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
]
}
},
"required": [
"location",
"unit"
]
},
"strict": true
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 291,
"output_tokens": 23,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 314
},
"user": null,
"metadata": {}
}OpenAI 嵌入格式（Embeddings）
获取给定输入文本的向量表示，这些向量可以被机器学习模型和算法轻松使用。
创建文本嵌入
curl https://<your-domain>/v1/embeddings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API_KEY>" \
-d '{
"input": "The food was delicious and the waiter...",
"model": "text-embedding-ada-002",
"encoding_format": "float"
}'响应示例：
{
"object": "list",
"data": [
{
"object": "embedding",
"embedding": [
0.0023064255,
-0.009327292,
// ... (1536 个浮点数,用于 ada-002)
-0.0028842222
],
"index": 0
}
],
"model": "text-embedding-ada-002",
"usage": {
"prompt_tokens": 8,
"total_tokens": 8
}
}批量创建嵌入
curl https://<your-domain>/v1/embeddings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API_KEY>" \
-d '{
"input": ["The food was delicious", "The waiter was friendly"],
"model": "text-embedding-ada-002",
"encoding_format": "float"
}'响应示例：
{
"object": "list",
"data": [
{
"object": "embedding",
"embedding": [
0.0023064255,
// ... (1536 个浮点数)
],
"index": 0
},
{
"object": "embedding",
"embedding": [
-0.008815289,
// ... (1536 个浮点数)
],
"index": 1
}
],
"model": "text-embedding-ada-002",
"usage": {
"prompt_tokens": 12,
"total_tokens": 12
}
}Jina AI 重排序格式（Rerank）
Jina AI Rerank 是一个强大的文本重排序模型，可以根据查询对文档列表进行相关性排序。该模型支持多语言，可以处理不同语言的文本内容，并为每个文档分配相关性分数。
在New API中，Jina AI 的 rerank 格式被采用为标准格式。所有其他供应商（如 Xinference、Cohere 等）的 rerank 响应都会被格式化为 Jina AI 的格式，以提供统一的开发体验。
基础重排序请求
curl https://<your-domain>/v1/rerank \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API_KEY>" \
-d '{
"model": "jina-reranker-v2-base-multilingual",
"query": "Organic skincare products for sensitive skin",
"top_n": 3,
"documents": [
"Organic skincare for sensitive skin with aloe vera and chamomile...",
"New makeup trends focus on bold colors and innovative techniques...",
"Bio-Hautpflege für empfindliche Haut mit Aloe Vera und Kamille..."
]
}'响应示例：
{
"results": [
{
"document": {
"text": "Organic skincare for sensitive skin with aloe vera and chamomile..."
},
"index": 0,
"relevance_score": 0.8783142566680908
},
{
"document": {
"text": "Bio-Hautpflege für empfindliche Haut mit Aloe Vera und Kamille..."
},
"index": 2,
"relevance_score": 0.7624675869941711
}
],
"usage": {
"prompt_tokens": 815,
"completion_tokens": 0,
"total_tokens": 815
}
}Xinference 重排序格式（Rerank）
在 New API 中，Xinference 的 rerank 响应结构将被格式化为 Jina 的 rerank 响应结构，因此使用 Xinference 重排序 API 时，只需将 model 参数设置为 Xinference 支持的重排序模型即可，其余参数和使用方式与 Jina AI 重排序 API 相同。
对于 Dify 等客户端用户：在配置时请选择 Jina AI 作为供应商类型，而不是 Xinference，并使用 Xinference 支持的模型名称。
基础重排序请求
curl https://<your-domain>/v1/rerank \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "jina-reranker-v2",
"query": "什么是美国的首都？",
"documents": [
"内华达州的首府是卡森城。",
"北马里亚纳群岛是太平洋上的一组岛屿，其首都是塞班岛。",
"华盛顿特区（也称为华盛顿或特区，正式名称为哥伦比亚特区）是美国的首都。",
"英语语法中的大写是在单词开头使用大写字母。英语用法与其他语言的大写不同。",
"自美国成为一个国家之前，美国就存在死刑。截至2017年，在50个州中有30个州死刑合法。"
],
"top_n": 3
}'OpenAI 音频格式
文本转语音
curl https://<your-domain>/v1/audio/speech \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "tts-1",
"input": "你好,世界!",
"voice": "alloy"
}' \
--output speech.mp3语音转文本
curl https://<your-domain>/v1/audio/transcriptions \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: multipart/form-data" \
-F file="@/path/to/file/audio.mp3" \
-F model="whisper-1"响应示例：
{
"text": "你好,世界!"
}音频翻译
curl https://<your-domain>/v1/audio/translations \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: multipart/form-data" \
-F file="@/path/to/file/chinese.mp3" \
-F model="whisper-1"响应示例：
{
"text": "Hello, world!"
}
评论区