讯飞星辰 MaaS 图像理解 HTTP 协议 - 图像分析 API 调用指南

1. 接口说明

协议：HTTP 请求方法：POST 默认请求地址如下：（请根据服务发布时间及在线推理页面展示，选择对应的接口地址）

https://maas-api.cn-huabei-1.xf-yun.com/v2（2026年1月10日及后发布服务的用户，请直接使用此新地址）
http://maas-api.cn-huabei-1.xf-yun.com/v1（2026年1月10日前已发布服务的存量用户，无需修改接口地址，仍可继续使用旧地址）

部分模型因为部署原因可能略有差异，具体可参考服务管控 > 模型服务列表右侧调用信息。技术咨询可直接提交工单

2. 接口请求

2.1 请求示例

如果想使用 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="<从服务管控页面获取 对应服务的ModelID>",  # 请根据实际情况替换为您的 Model ID
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": "这题的答案是什么"
                    },
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAbQAA..."
                        }
                    }
                ]
            }
        ],
        stream=True,
        temperature=0.7,
        max_tokens=8192
    )


    full_response = ""
    for chunk in response:
        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}")

注意：在使用demo之前，请务必替换 api_key 为您的API Key。

2.2 请求参数

参数	类型	是否必填	要求	说明
model	string	是		指定要调用的模型ID。请参考服务管控 > 模型服务列表获取。
messages	array	是	`[{"role": "user", "content": [...]}]`	表示对话上下文的消息列表。其中，`role` 用于标识消息发送方, `content` 则为包含文本和图像信息的数组。
stream	boolean	否	取值为 `true` 或 `false`，默认值为 `false`	指定是否采用流式响应模式。若设置为 `true`，系统将逐步返回生成的回复内容；否则，将一次性返回完整响应
temperature	float	否	取值为`[0,1]`,默认值为`0.7`	核采样阈值。用于决定结果随机性，取值越高随机性越强即相同的问题得到的不同答案的可能性越高
max_tokens	int	否	取值为`[1,8192]`，默认值为`2048`	限制生成回复的最大 token 数量

2.2.1 `messages` 参数说明

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

字段	含义	数据类型	取值范围	默认值	说明
role	角色	string	user		user表示用户的问题
content	内容	array	--		包含文本和图像信息的数组

content 数组内对象说明:

类型	字段	数据类型	说明
text	text	string	用户的文本输入
image_url	image_url	object	图像数据, 包含一个 `url` 字段

image_url 对象说明:

字段	数据类型	说明
url	string	图像的URL或者Base64编码的图像数据

示例：

[
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "这题的答案是什么"
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAbQAA..."
                }
            }
        ]
    }
]

3. 接口响应

3.1 响应示例

3.1.1 成功响应示例

流式响应会返回一系列的事件（data-only server-sent events），每个事件都是一个JSON对象，称为数据块（chunk）。下面是几个响应数据块的示例：

数据块 1 (包含内容):

{
  "id": "cht000b920a@dx194e0205ccbb8f3700",
  "object": "chat.completion.chunk",
  "created": 1738927005,
  "model": "xqwen2d5s32bvl",
  "choices": [
    {
      "index": 0,
      "delta": {
        "role": "assistant",
        "content": "这张图"
      },
      "finish_reason": null
    }
  ]
}

数据块 2 (继续包含内容):

{
  "id": "cht000b920a@dx194e0205ccbb8f3700",
  "object": "chat.completion.chunk",
  "created": 1738927005,
  "model": "xqwen2d5s32bvl",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "标显示的是..."
      },
      "finish_reason": null
    }
  ]
}

结束数据块 (finish_reason 为 stop):

{
  "id": "cht000b920a@dx194e0205ccbb8f3700",
  "object": "chat.completion.chunk",
  "created": 1738927005,
  "model": "xqwen2d5s32bvl",
  "choices": [
    {
      "index": 0,
      "delta": {},
      "finish_reason": "stop"
    }
  ],
  "usage": {
      "prompt_tokens": 44,
      "completion_tokens": 42,
      "total_tokens": 86
  }
}

3.1.2 异常结果示例

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

3.2 响应数据参数

在流式响应中，每个数据块（chunk）都包含以下字段：

字段名	类型	字段说明
id	string	唯一标识符，标识本次对话调用的唯一ID。
object	string	对象类型，对于流式响应，其值为 `chat.completion.chunk`。
created	int	响应生成时间的Unix时间戳（秒级）。
model	string	实际调用的模型名称。
choices	array	包含模型生成回复候选项的数组。
•index	int	回复候选项在数组中的索引位置，从0开始。
•delta	object	包含增量消息内容的对象。
◦role	string	在第一个数据块中出现，值为 `assistant`。
◦content	string	模型生成的增量回复文本内容。
•finish_reason	string	在最后一个数据块中出现，指示回复生成结束的原因，如 `"stop"`。
usage	object	在最后一个数据块中出现（需在请求中加入`stream_options={"include_usage": True}`），包含token使用统计信息。
•completion_tokens	int	回复文本消耗的token数量。
•prompt_tokens	int	输入prompt消耗的token数量。
•total_tokens	int	prompt与回复消耗token数量的总和。

4 . 错误码列表

4.1 HTTP状态码

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

4.2 业务逻辑错误码

除了标准的HTTP状态码，服务器在处理请求时也可能返回更详细的业务逻辑错误码。这些错误码通常包含在 500 Internal Server Error 等响应的 error 对象中。

错误码	错误信息
10000	升级为ws出现错误
10001	通过ws读取用户的消息出错
10002	通过ws向用户发送消息出错
10003	用户的消息格式有错误
10004	用户数据的schema错误
10005	用户参数值有错误
10006	用户并发错误：当前用户已连接，同一用户不能多处同时连接。
10007	用户流量受限：服务正在处理用户当前的问题，需等待处理完成后再发送新的请求。（必须要等大模型完全回复之后，才能发送下一个问题）
10008	服务容量不足，联系服务商
10009	和引擎建立连接失败
10010	接收引擎数据的错误
10011	向引擎发送数据的错误
10012	引擎内部错误
10013	用户问题涉及敏感信息，审核不通过，拒绝处理此次请求。
10014	回复结果涉及到敏感信息，审核不通过，后续结果无法展示给用户。（建议清空当前结果，并给用户提示/警告：该答案涉及到敏感/政治/恐怖/色情/暴力等方面，不予显示/回复）
10015	appid在黑名单中
10016	appid授权类的错误。比如：未开通此功能，未开通对应版本，token不足，并发超过授权等等。（联系我们开通授权或提高限制）
10018	用户在5分钟内持续发送ping消息，但并没有实际请求数据，会返回该错误码并断开ws连接。短链接使用无需关注
10019	该错误码表示返回结果疑似敏感，建议拒绝用户继续交互
10110	服务忙，请稍后再试。
10163	请求引擎的参数异常，引擎的schema检查不通过
10222	引擎网络异常
10223	LB找不到引擎节点
10907	token数量超过上限。对话历史+问题的字数太多，需要精简输入。
11200	授权错误：该appid没有相关功能的授权或者业务量超过限制（联系我们开通授权或提高限制）
11201	授权错误：日流控超限。超过当日最大访问量的限制。（联系我们提高限制）
11202	授权错误：秒级流控超限。秒级并发超过授权路数限制。（联系我们提高限制）
11203	授权错误：并发流控超限。并发路数超过授权路数限制。（联系我们提高限制）

5.3 内容审核说明

当返回10013或者10014错误码时，代码内容审核判断当前问题或回复的信息涉及敏感信息。返回错误的同时，在header.message字段中会携带当前的敏感提示语。

10013 表示用户的问题涉及敏感信息，服务侧拒绝处理此次请求。
10014 表示回复结果中涉及敏感信息，后续结果不可以展示给用户。
10019 表示当前的回复疑似敏感，结果文本可以给用户展示。服务会在返回全部结果后再返回该错误码，如果继续提问可能会导致被审核拦截。建议在收到该错误码后提示用户涉及敏感信息，并禁掉对话框，禁止用户继续提问。

如果需要调整内容审核的严格程度、敏感词等信息，请联系我们技术支持。

w3cschool 编程狮，随时随地学编程

讯飞星辰 MaaS 图像理解 HTTP 协议 - 图像分析 API 调用指南

1. 接口说明

2. 接口请求

2.1 请求示例

2.2 请求参数

2.2.1 messages 参数说明

3. 接口响应

3.1 响应示例

3.1.1 成功响应示例

3.1.2 异常结果示例

3.2 响应数据参数

4 . 错误码列表

4.1 HTTP状态码

4.2 业务逻辑错误码

5.3 内容审核说明

2.2.1 `messages` 参数说明