相关方案
      社区内容

        # 图像理解_HTTP协议

        # 1. 接口说明

        协议 ：HTTP 请求方法：POST 默认请求地址如下：

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

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

        # 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 表示当前的回复疑似敏感，结果文本可以给用户展示。服务会在返回全部结果后再返回该错误码，如果继续提问可能会导致被审核拦截。建议在收到该错误码后提示用户涉及敏感信息，并禁掉对话框，禁止用户继续提问。

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

        在这篇文章中：
        在线咨询
        体验中心