易缘 API / 接口文档
服务正常控制台 ↗
API Documentation

简单、统一的
AI API 接入方式

易缘 API 提供兼容 OpenAI 格式的统一接口。只需替换 Base URL 和 API Key，即可将现有应用接入多种模型。

OpenAI CompatibleHTTPS / JSONNew API v1.0.0-rc.24

快速开始

三步完成第一次请求。请先在控制台创建令牌，并妥善保管。

01 · 创建令牌

登录控制台，在「令牌」页面创建 API Key。

02 · 配置地址

将 SDK 的 Base URL 指向本站 API 根地址。

03 · 发起请求

使用兼容 OpenAI 的请求格式调用模型。

API 根地址
https://zzz.tuyang.online

认证方式

所有 API 请求都需要在 HTTP Header 中携带 Bearer Token。

HTTP Header
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Content-Type: application/json
请勿将 API Key 写入前端公开代码、提交到 Git 仓库，或发送给他人。建议通过服务端环境变量读取。

模型列表

获取当前账号可用的模型。返回格式与 OpenAI Models API 一致。

GET/v1/models
cURL
curl https://zzz.tuyang.online/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

对话补全

使用统一的 Chat Completions 接口进行文本对话，也支持流式输出。

POST/v1/chat/completions

请求示例

cURL · 非流式
curl https://zzz.tuyang.online/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "你的模型名称",
    "messages": [{"role": "user", "content": "你好，请介绍一下你自己。"}],
    "stream": false,
    "temperature": 0.7
  }'

常用参数

参数类型说明
modelstring模型名称，可通过 /v1/models 查询
messagesarray对话消息数组，支持 system / user / assistant
streamboolean是否启用 SSE 流式响应，默认 false
temperaturenumber采样温度，通常范围为 0–2
max_tokensinteger限制本次生成的最大 Token 数

流式响应

将 stream 设置为 true 后，服务会通过 Server-Sent Events 逐段返回内容，客户端读取以 data: 开头的事件，结束标记为 [DONE]。

向量嵌入

将文本转换为向量，适用于语义搜索、知识库和 RAG 场景。

POST/v1/embeddings
JavaScript
const response = await fetch('https://zzz.tuyang.online/v1/embeddings', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ model: '你的嵌入模型', input: '需要向量化的文本' })
});

错误处理

请求失败时，服务会返回标准 JSON 错误结构，请根据 HTTP 状态码进行处理。

状态码含义建议
400请求参数错误检查 JSON 格式、必填字段和参数类型
401认证失败检查 API Key 是否正确、是否已失效
403无权限访问确认令牌权限及模型访问权限
404资源不存在检查接口路径和模型名称
429请求过于频繁降低请求频率，并使用指数退避重试
5xx服务端错误稍后重试；持续发生时联系站点管理员
错误响应
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

SDK 示例

大多数 OpenAI 兼容 SDK 只需要修改 `base_url` 即可使用。

Python
from openai import OpenAI

client = OpenAI(
    api_key="你的 API Key",
    base_url="https://zzz.tuyang.online/v1",
)

completion = client.chat.completions.create(
    model="你的模型名称",
    messages=[{"role": "user", "content": "你好！"}],
)
print(completion.choices[0].message.content)
Node.js
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: 'https://zzz.tuyang.online/v1'
});