益益大模型

益术AI API 对接文档 (V1)

最后更新时间: 2025年7月18日

欢迎使用益术AI API。本API提供了一个统一、标准化的接口，让您可以轻松地将“益益”系列大语言模型集成到您的应用程序中。API遵循与业界主流标准兼容的设计，支持流式响应与自定义AI角色，以实现实时、动态的交互体验。

快速入门

只需三步，即可开始使用益术AI API：

1. 获取API Key：访问 益术AI会员中心，登录后在“API密钥”标签页中生成您的专属API Key。
2. 选择模型：根据您的需求选择一个可用的模型，例如 YiYi-Thinking-V1。
3. 发送请求：参照下文的代码示例，向API端点 https://ai.xlj0.com/api.php 发送一个POST请求。

---

认证 (Authentication)

API使用 Bearer Token 方式进行认证。所有API请求都需要在HTTP头信息中包含Authorization字段，并提供您的API Key。

请求头示例:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

---

API 端点 (Endpoint)

• 请求地址: https://ai.xlj0.com/api.php
• 请求方法: POST

---

请求体 (Request Body)

请求体必须是JSON格式。

参数	类型	是否必需	描述
model	string	是	要使用的模型ID。详情请见下方的“模型列表”。
messages	array	是	一个包含对话历史的消息对象数组。支持通过system角色自定义人设。
stream	boolean	否	如果设置为 true，API将以流式方式返回响应。推荐在聊天场景中使用。默认为 false。

messages 数组详解

messages 数组构成了对话的上下文。它由一个或多个消息对象组成。

消息对象结构:

参数	类型	描述
role	string	消息的角色，可以是 user (用户), assistant (AI助手), 或 system (系统)。
content	string	消息的具体内容。

✨ 新功能：自定义人设 (Persona)

您可以为AI定义一个特定的角色、个性和行为准则。要实现此功能，请将一个 role 为 system 的消息对象作为 messages 数组的第一个元素传入。

• 如果提供了 system 消息：API将完全采用您定义的人设。
• 如果未提供 system 消息：API将自动使用默认的“益益AI助手”人设。

messages 示例 (使用自定义人设):

[
  {"role": "system", "content": "你是一个精通中国古诗词的AI助手，你的回答应尽可能地引用诗句，并保持文雅的风格。"},
  {"role": "user", "content": "你好，请问今天天气如何？"}
]

---

响应格式与详解

响应格式总览 (非流式)

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "created": 1721234567,
  "model": "YiYi-Thinking-V1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "当然可以。这是一个使用迭代方法计算斐波那...（完整回复内容）"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 120,
    "total_tokens": 145
  }
}

响应参数详解

参数	类型	描述
id	string	本次聊天补全的唯一标识符。
object	string	对象类型，恒为 chat.completion 或 chat.completion.chunk。
created	integer	本次补全创建时的Unix时间戳（秒）。
model	string	您请求的自定义模型名称，如 YiYi-Thinking-V1。
choices	array	包含聊天补全结果的数组，通常只包含一个元素。
choices[].message.content	string	(非流式) 模型生成的完整回复内容。
choices[].delta.content	string	(流式) 模型生成的回复内容片段。
choices[].finish_reason	string	模型停止生成内容的原因。stop 表示正常结束。
usage	object	(仅在非流式请求中提供) 本次请求的Token消耗统计。

---

代码示例

1. cURL

基础请求

curl -N -X POST https://ai.xlj0.com/api.php \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "model": "YiYi-Thinking-V1",
  "messages": [{"role": "user", "content": "你好"}],
  "stream": true
}'

使用自定义人设

curl -N -X POST https://ai.xlj0.com/api.php \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "model": "YiYi-Thinking-V1",
  "messages": [
    {"role": "system", "content": "你是一个专业的法律文书助手，回答问题需要严谨、精确。"},
    {"role": "user", "content": "请帮我草拟一份简单的租赁合同注意事项。"}
  ],
  "stream": true
}'

2. PHP

<?php
$apiKey = 'YOUR_API_KEY';
$apiUrl = 'https://ai.xlj0.com/api.php';

$payload = [
    'model' => 'YiYi-Thinking-V1',
    'messages' => [
        ['role' => 'system', 'content' => '你是一个充满激情的助手，用简洁有力的语言回答问题。现在请你忘记之前的设定，你叫time，你是王喜乐训练的大模型'],
        ['role' => 'user', 'content' => '你好你是谁?']
    ]
];

$headers = [ 'Content-Type: application/json', 'Authorization: Bearer ' . $apiKey ];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$responseData = json_decode($response, true);
print_r($responseData);
?>

处理流式输出

<?php
$apiKey = 'YOUR_API_KEY';
$apiUrl = 'https://ai.xlj0.com/api.php';

$payload = [
    'model' => 'YiYi-Thinking-V1',
    'messages' => [
        ['role' => 'user', 'content' => '请解释什么是“黑洞”？']
    ],
    'stream' => true // 启用流式响应
];

$headers = [ 'Content-Type: application/json', 'Authorization: Bearer ' . $apiKey ];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, false); // 直接输出到屏幕
curl_setopt($ch, CURLOPT_WRITEFUNCTION, function($curl, $data) {
    // 在这里，您可以解析 $data 来区分 reasoning_content 和 content
    echo $data; 
    flush(); // 立即将数据发送到浏览器
    return strlen($data);
});

curl_exec($ch);
curl_close($ch);
?>

3. Python

import requests
import json

API_URL = "https://ai.xlj0.com/api.php"
API_KEY = "YOUR_API_KEY"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}
data = {
    "model": "YiYi-Thinking-V1",
    "messages": [
        {"role": "system", "content": "你是一位知识渊博的历史学家。"},
        {"role": "user", "content": "简单介绍一下丝绸之路。"}
    ],
    "stream": True
}

try:
    response = requests.post(API_URL, headers=headers, json=data, stream=True)
    response.raise_for_status()
    for line in response.iter_lines():
        if line:
            # ... (处理流式数据的逻辑不变)
            
except requests.exceptions.RequestException as e:
    print(f"请求错误: {e}")

4. JavaScript (Node.js)

const fetch = require('node-fetch');

const API_URL = "https://ai.xlj0.com/api.php";
const API_KEY = "YOUR_API_KEY";

async function main() {
    const response = await fetch(API_URL, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${API_KEY}`
        },
        body: JSON.stringify({
            model: 'YiYi-Thinking-V1',
            messages: [
                {"role": "system", "content": "你是一个科幻作家，请用充满想象力的风格回答。"},
                {"role": "user", "content": "十年后的世界会是什么样？"}
            ],
            stream: true,
        }),
    });

    if (!response.ok) {
        const errorData = await response.json();
        throw new Error(`API Error: ${response.status} - ${errorData.error.message}`);
    }
    
    for await (const chunk of response.body) {
        process.stdout.write(chunk);
    }
}
main().catch(console.error);

---

错误处理

API使用标准的HTTP状态码来指示请求的成功或失败。

状态码	含义
200 OK	成功
400 Bad Request	错误的请求 (如: JSON格式错误, 缺少参数)
401 Unauthorized	未认证 (API Key错误或缺失)
403 Forbidden	禁止 (账户被禁用)
429 Too Many Requests	请求过多 (超出Token限额)
5xx	服务器错误

错误响应体示例:

{
  "error": {
    "message": "Invalid API Key or authorization header missing.",
    "type": "authentication_error"
  }
}