# 精调服务_HTTP协议

# 1. 接口说明

协议：HTTP 请求方法：POST

若使用 http client 的方式，直接发起request请求，地址如下：

https://maas-api.cn-huabei-1.xf-yun.com/v1/chat/completions

若使用 openai sdk，url地址如下：

https://maas-api.cn-huabei-1.xf-yun.com/v1

部分模型因为部署原因可能略有差异，具体可参考服务管控 > 模型服务列表右侧调用信息。

# 2. 接口请求

# 2.1 请求示例

下面基于openAI SDK请求的 Python Demo 示例：

from openai import OpenAI  

api_key = "<从服务管控页面获取 对应服务的APIKey>"  # 请替换为您的 API Key  
api_base = "http://maas-api.cn-huabei-1.xf-yun.com/v1"  

client = OpenAI(api_key=api_key,base_url=api_base)  

try:
    response = client.chat.completions.create(
        model="<从服务管控获取要访问服务的serviceID>",
        messages=[{"role": "user", "content": "你好"}],
        stream=False,
        temperature=0.7,
        max_tokens=4096,
        extra_headers={"lora_id": "0"},  
        stream_options={"include_usage": True} 
    )

    print(response.choices[0].message.content)
    
except Exception as e:
    print(f"Error: {e}")

注意：在执行此代码之前，请务必替换 api_key 为您的API Key。

如果想使用 HTTP 请求的流式输出，请参考如下实例：

from openai import OpenAI  

api_key = "<从服务管控页面获取 对应服务的APIKey>"  # 请替换为您的 API Key  
api_base = "http://maas-api.cn-huabei-1.xf-yun.com/v1"  

client = OpenAI(api_key=api_key,base_url=api_base)  

try:
    response = client.chat.completions.create(
        model="<从服务管控获取要访问服务的serviceID>",
        messages=[{"role": "user", "content": "你好"}],
        stream=True,
        temperature=0.7,
        max_tokens=4096,
        extra_headers={"lora_id": "0"},  
        stream_options={"include_usage": True} 
    )

    full_response = ""
    for chunk in response:
        # 只对支持深度思考的模型才有此字段
        if hasattr(chunk.choices[0].delta, 'reasoning_content') and chunk.choices[0].delta.reasoning_content is not None:
            reasoning_content = chunk.choices[0].delta.reasoning_content
            print(reasoning_content, end="", flush=True)  # 实时打印思考模型输出的思考过程每个片段
        
        if hasattr(chunk.choices[0].delta, 'content') and chunk.choices[0].delta.content is not None:
            content = chunk.choices[0].delta.content
            print(content, end="", flush=True)  # 实时打印每个片段
            full_response += content
    
    print("\n\n ------完整响应：", full_response)    
except Exception as e:
    print(f"Error: {e}")

注意：在运行此代码之前，请务必替换 api_key 为您的API Key。

# 2.2 请求参数

参数	类型	是否必填	要求	说明
model	string	是		指定要调用的对话生成模型ID
messages	array	是	`[{"role": "user", "content":"用户输入内容"}]`	表示对话上下文的消息列表，支持多轮对话交互。其中，`role` 用于标识消息发送方（例如 `user` 表示用户、`assistant` 表示模型回复、 `system` 用以设置对话背景信息），`content` 则为实际文本内容。
stream	boolean	否	取值为 `true` 或 `false`，默认值为 `false`	指定是否采用流式响应模式。若设置为 `true`，系统将逐步返回生成的回复内容；否则，将一次性返回完整响应
temperature	float	否	取值为`[0,1]`,默认值为`0.7`	核采样阈值。用于决定结果随机性，取值越高随机性越强即相同的问题得到的不同答案的可能性越高
max_tokens	int	否	取值为`[1,32768]`，默认值为`2048`	限制生成回复的最大 token 数量，max_tokens的限制需要满足`输入promptToken + 设置参数max_tokens <= 32768 - 1`,参数设置过大可能导致回答中断，请酌情调整，建议取值16384以下
extra_headers	object	否	默认值为`{"lora_id": "0"}`	通过传递 `lora_id` 加载特定的LoRA模型
stream_options	object	否	默认值为`{"include_usage": True}`	针对流式响应模式的扩展配置，如控制是否在响应中包含API调用统计信息等附加数据。

# 2.2.1 `messages` 参数说明

messages 参数用于传递对话内容，包括用户输入和 AI 回复

字段	含义	数据类型	取值范围	默认值	说明
role	角色	string	system,user,assistant		通过system设置对话背景信息，user表示用户的问题，assistant表示AI的回复
content	文本内容	string	--		该角色的对话内容

示例：单轮交互 单轮交互只需要传递一个user角色的数据

[
    {"role": "user", "content": "你会做什么？"}  
]

示例：多轮交互 多轮交互需要将之前的交互历史按照user->assistant->user->assistant规则进行拼接，并保证最后一条是user的当前问题。

[
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好！"},
    {"role": "user", "content": "你是谁？"},
    {"role": "assistant", "content": "我是 Spark API。"},
    {"role": "user", "content": "你会做什么？"}
]

# 3. 接口响应

# 3.1 响应示例

# 3.1.1 成功响应示例

Response: ChatCompletion(
    id='cht000b920a@dx194e0205ccbb8f3700',
    choices=[
        Choice(
            finish_reason='stop',
            index=0,
            logprobs=None,
            message=ChatCompletionMessage(
                content='大模型回复',
                refusal=None,
                role='assistant',
                audio=None,
                function_call=None,
                tool_calls=None
            )
        )
    ],
    created=1738927005,
    model=None,
    object='chat.completion',
    service_tier=None,
    system_fingerprint=None,
    usage=CompletionUsage(
        completion_tokens=42,
        prompt_tokens=44,
        total_tokens=86,
        completion_tokens_details=None,
        prompt_tokens_details=None
    )

# 3.1.2 异常结果示例

Error: Error code: 403 - {'error': {'message': '该令牌无权使用模型：xqwen257bxxx (request id: 2025020809381060443349905703260)', 'type': 'one_api_error'}}

# 3.2 响应数据参数

字段说明如下：

字段名	类型	字段说明
id	string	唯一标识符，标识本次对话调用的唯一ID，用于跟踪和调试
choices	array	包含模型生成回复候选项的数组
•finish_reason	string	指示回复生成结束的原因，如`"stop"`
•index	int	回复候选项在数组中的索引位置，从0开始
•logprobs	object	如启用token概率日志，则返回具体信息
•message	object	描述回复消息内容的对象，其内部字段如下
◦content	string	模型生成的回复文本内容
◦reasoning_content	string	模型生成的思考文本内容(支持深度思考的模型才有此字段)
◦refusal	object	模型拒绝回答时返回拒绝信息
◦role	string	消息发送方，通常为`"assistant"`
◦audio	object	如支持语音回复则返回音频数据
◦function_call	objec	模型调用外部函数时返回调用信息
◦tool_calls	object	模型调用工具时返回调用详情，
created	int	响应生成时间的Unix时间戳（秒级）
model	string	实际调用的模型名称
object	string	表示响应对象类型
service_tier	string	表示调用所属的服务层级
system_fingerprint	string	系统指纹或配置标识
usage	object	包含token使用统计信息，其内部字段如下：
•completion_tokens	int	回复文本消耗的token数量
•prompt_tokens	int	输入prompt消耗的token数量
•total_tokens	int	prompt与回复消耗token数量的总和
•completion_tokens_details	object	回复生成过程中token的详细统计信息，若无则为`null`
•prompt_tokens_details	object	prompt部分token的详细统计信息

# 4 . 错误码列表

错误码	原因	解决方案
401-无效的身份验证	身份验证无效。	确保使用正确的API密钥及请求组织。
401-提供的API密钥不正确	请求的API密钥不正确。	检查所用API密钥是否正确，清除浏览器缓存或生成新的密钥。
403-不支持的国家、地区或领土	您正在从不支持的国家、地区或领土访问API。	请参考相关页面获取更多信息。
429-请求速率限制已达上限	您发送请求过快。	控制请求频率，阅读速率限制指南。
429-超出当前配额，请检查计划和计费详情	您的额度已用尽或已达到每月最高消费限制。	购买更多额度或了解如何提高使用限制。
500-服务器处理请求时发生错误	服务器内部出现问题。	稍后重试请求；若问题持续，请联系我们查看状态页面。
503-引擎当前过载，请稍后重试	服务器流量过大。	稍候重试您的请求。

在这篇文章中：