跳到主要内容

元象大模型 OpenAPI 调用指南

为方便用户使用,我们提供了原生 HTTP 来实现模型 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;
(4)对话 message 的总长度(即包含历史的所有对话长度)不能超过 6144 个 token,超过后系统会做截断处理。
rolestring对话角色,user 或 assistant
contentstring对话内容,注意最后一轮对话信息不可超过 6144个 token,否则会截断
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": "静夜思的作者是谁?"
}
],
"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.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无效的身份验证确保使用正确的 APIKey
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发送请求的速度太快当前请求过于频繁,请稍后再试