跳到主要内容

元象大模型 OpenAPI 调用指南

为方便用户使用，我们提供了原生 HTTP 和 OpenAI 兼容的 SDK 来实现模型 API 的调用，主要分为两步：

  1. 创建 APIKey ；
  2. 通过 APIKey 访问对话 API。

1. 创建APIKey​

访问官网开放平台中的开发者中心，完成实名认证、充值后即可创建APIKey。

2. 开始对话​

拿到 APIKey 信息后，调用本接口，开始进行对话。

2.1 请求说明​

2.1.1 基本信息​

接口信息说明
请求地址https://api.xverse.cn
接口路径/v1/chat/completions
接口请求类型POST
字符编码UTF-8

2.1.2 Header参数​

参数名类型是否必填描述
Content-TypestringY请求的数据格式，目前仅支持 JSON 格式，固定值：application/json
AuthorizationstringY请求鉴权的 APIKey，由元象提供，Bearer 开头

2.1.3 Body参数​

参数名一级子参数类型必填描述
messages-List[json]是聊天上下文信息，说明：
（1）messages 列表中的成员不能为空，1个成员表示单轮对话，多个成员表示带有历史信息；
（2） messages 列表中的最后一个 message 信息为当前请求信息，前面的 message 为历史对话信息；
（3）成员中的 role 必须依次为 user、assistant，否则会影响对话效果。
rolestring是对话角色，user、assistant 或 system。其中 system 角色只能出现在首句，最后一句对话角色一定是 user
contentstring是对话内容，说明：
所有对话内容的总 Token 数不可超过 6144，否则会截断，截断时会保留 system 角色的内容。
model-string是使用的模型 ID，模型列表：
XVERSE-13B-2
XVERSE-65B-2
max_tokens-int否生成的最大 token 数量，默认为 2048，取值范围 [0, 2048]，传 0 会取默认值
top_k-int否影响输出文本的多样性，取值越大，生成文本的多样性越强，默认为30，取值范围[0, 100]，传 0 会取默认值
top_p-float否（1）影响输出文本的多样性，取值越大，生成文本的多样性越强。
（2）该参数默认为0.85，取值范围 [0, 1]，传 0 会取默认值。
（3）为使效果更好，建议该参数和 temperature 只设置 1 个。
（4）建议 temperature 和 top_p 不要同时更改。
temperature-float否（1）较高的数值会使输出更加随机，较低数值会使输出更加集中和确定。（2）该参数默认为0.5，取值范围 [0, 1]，传 0 会取默认值。
（3）为使效果更好，建议该参数和 top_p 只设置 1 个。
（4）建议 temperature 和 top_p 不要同时更改。
presence_penalty-float否（1）这个参数用于减少生成文本中的重复内容，值越大代表越严格控制重复度。
（2）该参数默认值为1.1，取值范围 [1, 3]，传 0 会取默认值。
user_id-string否用户 ID，用户唯一标识，如果填写，需跟 APIKey 对应上。
dialog_id-string否对话ID，由客户端生成随机的唯一 ID，标识多通同类型的对话，为 20-36 位字符串，可包含字母和数字、中划线和下划线。
trace_id-string否链路 ID，由客户端生成随机的唯一 ID，标识整通对话，为 20-36 位字符串，可包含字母和数字、中划线和下划线。
stream-bool否是否使用流式接口，缺省值为 false

2.2 请求示例​

2.2.1 cURL 示例​

curl --location -XPOST 'https://api.xverse.cn/v1/chat/completions' \
--header 'Authorization: Bearer ${api_key}' \
--header 'Content-Type: application/json' \
--data '{
      "messages":[
            {
                  "role":"user",
                  "content": "你是谁？"
            },
            {
                  "role":"assistant",
                  "content": "我是智能对话助手。"
            },
            {
                  "role":"user",
                  "content": "静夜思的作者是谁？"
            }
      ]
}'

2.2.2 python 示例​

我们默认您已经在计算机上安装了 Python3.6 及以上版本，并且可以使用 pip 来拉取三方开源库。

​ 1）导入处理 SSE 的标准三方库：

pip install sseclient-py

​ 2）新建文件，执行以下代码：

import requests
from sseclient import SSEClient
import json

def process_sse(response):
    # 使用SSEClient处理流式数据
    client = SSEClient(response)

    # 初始化一个空字符串用于拼接内容
    concatenated_data = ""

    # 遍历SSE事件
    for event in client.events():
            data_json = event.data
            # 解析SSE事件的data字段，这里data是一个JSON字符串
            data_dict = json.loads(data_json)

            choices = data_dict.get('choices', [])

            for ch in choices:
                content_data = ch.get('delta', {})
                finish_reason = ch.get('finish_reason', '')
                content = content_data.get('content', '')

                # 还在进行中
                if finish_reason == '':
                    # 拼接内容
                    print(content, end='')
                    concatenated_data += content

                # 结束循环，因为数据流结束了
                elif finish_reason == 'stop':
                    break

                # 被过滤的数据进行处理
                elif finish_reason == 'content_filter':
                    print(content, end='')
                    concatenated_data += "「trigger sensitive」"
                    break

def process_non_sse(response):
    response_content = json.loads(response.content.decode('utf-8'))
    choices = response_content.get('choices', [])
    if len(choices) > 0:
        ch = choices[0]
        print(ch.get("message", {}).get("content", {}))

def fetch_chat_data(url, api_key, body_data):
    # 构建请求头信息
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json',  # 设置请求体类型为 JSON
    }
    try:
        # 发送带有头信息和请求体的 POST 请求
        response = requests.post(url, stream=True, headers=headers, data=json.dumps(body_data))

        # 检查响应状态码
        response.raise_for_status()

        if body_data.get('stream'):
            process_sse(response)
        else:
            process_non_sse(response)

    except json.JSONDecodeError as e:
        print(f"Error decoding JSON: {e}")
        raise e

    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")


if __name__ == "__main__":
    # 改为开发者中心新建的API Key
    api_key = 'xxxxxx'
    path = "/v1/chat/completions"
    domain = "https://api.xverse.cn"

    # 传入您想要对话的内容及上下文信息
    body_data = {
        "messages": [
            {
                "role": "user",
                "content": "你是谁"
            },
            {
                "role": "assistant",
                "content": "我是智能对话助手"
            },
            {
                "role": "user",
                "content": "静夜思的作者是谁？"
            }
        ],
        "model":"XVERSE-65B-2",
        "stream": True
    }
    # 流式处理
    print("以下为流式处理：")
    fetch_chat_data(domain + path, api_key, body_data)

    # 非流式处理
    body_data['stream'] = False
    print("\n\n以下为非流式处理：")
    fetch_chat_data(domain + path, api_key, body_data)

2.2.3 OpenAI SDK示例​

我们默认您已经在计算机上安装了 Python3.6 及以上版本，并且可以使用 pip 来拉取三方开源库。

1）导入处理 OpenAI 的标准三方库：

pip install openai

2）新建文件，执行如下代码：

import openai

client = openai.Client(
    base_url="https://api.xverse.cn/v1",
    api_key="xxxxxx", # 改为开发者中心新建的API Key
)

result = client.chat.completions.create(
    model="XVERSE-65B-2",
    messages=[
        {"role": "user", "content": "静夜思的作者是谁"},
    ]
)

print(result)

2.3 响应说明​

2.3.1 同步接口响应​

2.3.1.1 HTTP Header 响应参数​
参数名类型描述
Content-Typestring响应的数据格式
X-Request-Idstring请求的唯一标识 ID
2.3.1.2 HTTP Body 响应参数​
字段名一级子参数二级子参数类型描述
id--string'Chat completion' 的唯一标识
objectstringObject类型，始终为chat.completion
created--int创建聊天完成时的 Unix 时间戳（秒）
choices--array[json]聊天完成选项的列表，目前只返回一条
finish_reason-string模型停止生成 token 的原因，为以下值：
（1） stop ：模型达到自然停止点/用户 stop 指令；
（2） error：参数验证不通过或者服务内部错误
index-intchoices 中对应的索引
message-json模型生成的聊天完成消息
rolestring生成消息的角色，目前默认为 assistant（模型）
contentstring消息内容
usagejson完成请求的使用情况统计信息
completion_tokens-int生成词中的 token 数
prompt_tokens-int提示词中的 token 数
total_tokens-int会话的总 token 数
error_infojson对话错误提示信息
code-int正常为0，否则会根据错误类型给出对应的code，如 10001，10005 等
message-string正常为空字符串，否则会根据错误类型给出对应的错误提示，如 10001：服务内部错误，10005：鉴权失败 等
2.3.1.2 HTTP 响应示例​
{
      "id": "0SIJv20YYgXQckgRTAm8",
      "object": "chat.completion",
      "created": 1701332022,
      "choices": [
            {
                  "finish_reason": "stop",
                  "index": 0,
                  "message": {
                        "role": "assistant",
                        "content": "《静夜思》是唐代诗人李白创作的一首著名五言绝句。全诗如下：\n\n床前明月光，疑是地上霜。\n举头望明月，低头思故乡。\n\n这首诗表达了诗人在寂静的夜晚看到明亮的月光时，不禁想起远方的家乡和亲人的情感。"
                  }
            }
      ],
      "usage": {
            "prompt_tokens": 48,
            "completion_tokens": 103,
            "total_tokens": 151
      },
      "error_info": {
            "code": 0,
            "message": ""
      }
}

2.3.2 流式接口响应​

2.3.2.1 HTTP Header 响应参数​
参数名类型描述
Content-Typestring响应的数据格式
X-Request-Idstring请求的唯一标识 ID
2.3.2.2 HTTP Body 响应参数​
字段名一级子参数二级子参数类型描述
id--string'Chat completion' 的唯一标识
created--int创建聊天完成时的 Unix 时间戳（秒）
choices--array[json]聊天完成选项的列表
finish_reason-string模型停止生成 token 的原因，为以下值：
（1） stop ：模型达到自然停止点/用户 stop 指令；
（2）content_filter：内容被过滤，并停止数据发送；
（3） error：参数验证不通过或者服务内部错误
index-intchoices 中对应的索引
delta-json模型生成的聊天完成消息
rolestring生成消息的角色，目前默认为 assistant（模型）
contentstring消息内容
objectstringObject类型，始终为chat.completion.chunk
usagejson完成请求的使用情况统计信息，只有最后的一次回复才有值
completion_tokens-int生成词中的 token 数
prompt_tokens-int提示词中的 token 数
total_tokens-int会话的总 token 数
error_infojson对话错误提示信息
code-int正常为0，否则会根据错误类型给出对应的code，如 -998，10005 等
message-string正常为空字符串，否则会根据错误类型给出对应的错误提示，如 -998：对话异常，10005：鉴权失败 等
2.3.2.2 HTTP 流式响应示例​
data: {"id":"IS0rbYH0BYBcActfCkAh","object":"chat.completion.chunk","created":1701329023,"choices":[{"finish_reason":"","index":0,"delta":{"role":"assistant","content":"《"}}],"error_info": {"code": 0,"message":""}}

data: {"id":"IS0rbYH0BYBcActfCkAh","object":"chat.completion.chunk","created":1701329023,"choices":[{"finish_reason":"","index":0,"delta":{"role":"assistant","content":"静"}}],"error_info": {"code": 0,"message":""}}

data: {"id":"IS0rbYH0BYBcActfCkAh","object":"chat.completion.chunk","created":1701329023,"choices":[{"finish_reason":"","index":0,"delta":{"role":"assistant","content":"夜"}}],"error_info": {"code": 0,"message":""}}

data: {"id":"IS0rbYH0BYBcActfCkAh","object":"chat.completion.chunk","created":1701329023,"choices":[{"finish_reason":"","index":0,"delta":{"role":"assistant","content":"思"}}],"error_info": {"code": 0,"message":""}}

data: {"id":"IS0rbYH0BYBcActfCkAh","object":"chat.completion.chunk","created":1701329023,"choices":[{"finish_reason":"","index":0,"delta":{"role":"assistant","content":"》"}}],"error_info": {"code": 0,"message":""}}

...

data: {"id":"IS0rbYH0BYBcActfCkAh","object":"chat.completion.chunk","created":1701329023,"choices":[{"finish_reason":"stop","index":0,"delta":{}}],"usage":{"prompt_tokens": 48,"completion_tokens": 22,"total_tokens": 70},"error_info": {"code": 0,"message":""}}

2.4 状态码​

应答 Headers 中支持 HTTP 标准状态码，具体如下：

HTTP 状态码描述(错误)原因解决方案
200success--
401Invalid Authentication无效的身份验证1）确保使用正确的 APIKey；2）确保用户账号有充足权限
402Status Payment Required账户余额不足充值，使得账户余额大于0
429Rate limit reached for requests发送请求的速度太快调整您的请求速率
500Internal Server Error服务提供方服务器上的问题在短暂等待后重试您的请求，如果问题仍然存在，请与我们联系

2.5 错误码​

应答 error_info 中定义了具体的错误类型，如下所示：

code描述(错误)原因解决方案
0---
-996~-999Abnormal Conversation对话异常请换个话题再试
10001Internal Server Error服务内部错误在短暂等待后重试您的请求，如果问题仍然存在，请与我们联系
10002Bad Request请求入参有误请检查您的请求入参类型
10005~10007Authentication Failed用户鉴权失败请检查您的APIKey是否填写正确
20409~20411Internal Server Error服务内部错误在短暂等待后重试您的请求，如果问题仍然存在，请与我们联系
20416Too Many Conversations对话数量过多当前对话数过多，请稍后重试
20501~20511Bad Request请求入参有误请检查您的请求入参
20601Insufficient Balance余额不足请充值后重试
20602Request Too Frequent发送请求的速度太快当前请求过于频繁，请稍后再试