API 参考

NexusModels 提供统一的 RESTful API，用于调用多种人工智能模型。

接口兼容 OpenAI API 格式，并根据模型能力支持文本、向量、音频、图像和视频等不同类型的请求。

接口可用性

不同模型支持的接口和参数可能不同。实际可用模型请通过模型列表接口查询。

AI 模型接口

API	常用接口	说明
模型 Models	GET /v1/models	获取当前 API Key 可用的模型列表
聊天 Chat	POST /v1/chat/completions	创建多轮对话补全，支持普通和流式输出
Responses	POST /responses	使用 OpenAI Responses 格式创建模型响应
Completions	POST /completions	传统文本补全接口
Embeddings	POST /embeddings	将文本转换为向量
Rerank	POST /rerank	根据相关性重新排列文档
Moderations	POST /moderations	对输入内容进行安全审查
Realtime	WebSocket实时接口	实时文本和音频交互
Audio	/audio/speech、/audio/transcriptions、/audio/translations	语音合成、语音转录和翻译
Images	/images/generations、/images/edits	图像生成和编辑
Videos	模型相关视频接口	AI视频生成

接口是否可用取决于：

• 当前 API Key 可以访问的模型
• 所选模型支持的输入和输出类型
• 模型服务当前是否启用
• 上游模型服务的接口兼容性

基本约定

API Base URL

OpenAI SDK 和大多数客户端应使用：

https://api.nexusmodels.cn/v1

完整接口示例：

https://api.nexusmodels.cn/v1/chat/completions

身份认证

所有模型接口都必须在请求头中携带 NexusModels API Key：

Authorization: Bearer YOUR_NEXUSMODELS_API_KEY

示例：

curl https://api.nexusmodels.cn/v1/models \
  -H "Authorization: Bearer YOUR_NEXUSMODELS_API_KEY"

请妥善保管 API Key，不要将真实 Key：

• 提交到公开代码仓库
• 写入浏览器前端代码
• 输出到公开日志
• 分享给未授权人员

请求格式

GET 请求通常通过 Query String 传递参数：

GET /v1/models

POST 请求通常使用 JSON Body：

Content-Type: application/json

示例：

{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ]
}

文件上传接口可能使用：

Content-Type: multipart/form-data

响应格式

大多数接口返回 JSON 数据。

常见字段包括：

字段	类型	说明
id	string	请求或响应的唯一标识
object	string	返回对象类型
model	string	实际使用的模型
created	integer	响应创建时间
choices	array	模型生成结果
usage	object	Token使用情况

聊天响应示例：

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "created": 1780000000,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好，我可以为你提供什么帮助？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}

流式接口使用 Server-Sent Events 返回分段结果：

Content-Type: text/event-stream

音频、图片等接口也可能返回文件地址或二进制内容，具体取决于模型和接口。

快速请求

查询模型

curl https://api.nexusmodels.cn/v1/models \
  -H "Authorization: Bearer YOUR_NEXUSMODELS_API_KEY"

创建聊天请求

curl https://api.nexusmodels.cn/v1/chat/completions \
  -H "Authorization: Bearer YOUR_NEXUSMODELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "user",
        "content": "你好"
      }
    ]
  }'

创建流式请求

curl https://api.nexusmodels.cn/v1/chat/completions \
  -H "Authorization: Bearer YOUR_NEXUSMODELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "user",
        "content": "请介绍人工智能"
      }
    ],
    "stream": true
  }'

错误处理

接口错误通常使用以下格式：

{
  "error": {
    "message": "错误描述",
    "type": "error_type",
    "param": null,
    "code": "error_code"
  }
}

常见 HTTP 状态码：

HTTP状态码	错误类型	说明
400	invalid_request_error	请求参数或请求格式错误
401	authentication_error	API Key缺失、无效或已停用
403	permission_error	无权使用指定模型或接口
404	not_found_error	模型或接口不存在
429	rate_limit_error	超出速率、用量或账户限制
500	api_error	NexusModels内部错误
502	upstream_error	上游模型服务返回错误
503	service_unavailable	服务暂时不可用

客户端应根据状态码决定是否重试。对于 500、502 和 503，建议使用有限次数的指数退避重试。

查看完整错误处理说明