# 图片理解 API 文档

# 服务说明

本服务是星火大模型训练的视觉模型,支持用于基于上传的图片内容进行理解、推理和问答。 近期,整体效果全面升级,在万物识别方面重点提升识别准确性,增强推理能力

# 调用示例

图片理解 demo python语言 (opens new window)
图片理解 demo java语言 (opens new window)
图片理解 demo go语言 (opens new window)

# 接口要求

内容 说明
传输方式 ws[s] (为提高安全性,强烈推荐wss)
请求地址 wss://spark-api.cn-huabei-1.xf-yun.com/v2.1/image
注:服务器IP不固定,为保证您的接口稳定,请勿通过指定IP的方式调用接口,使用域名方式调用
Content-Type application/json;charset=UTF-8
接口鉴权 签名机制,详情请参照签名生成 (opens new window)
字符编码 UTF-8
响应格式 统一采用JSON格式
开发语言 任意,只要可以向讯飞云服务发起HTTP请求的均可
适用范围 任意操作系统,但因不支持跨域不适用于浏览器
图片格式 .jpg、.jpeg、.png
图片大小 4M

# 鉴权说明

在调用业务接口时,请求方需要对请求进行签名,服务端通过签名来校验请求的合法性。

# 鉴权方法

详情请参照下方签名生成 (opens new window)

# 鉴权结果

如果鉴权失败,则根据不同错误类型返回不同HTTP Code状态码,同时携带错误描述信息,详细错误说明如下:

HTTP Code 说明 错误描述信息 解决方法
401 缺少authorization参数 {"message":"Unauthorized"} 检查是否有authorization参数,详情见authorization参数详细生成规则
401 签名参数解析失败 {“message”:”HMAC signature cannot be verified”} 检查签名的各个参数是否有缺失是否正确,特别确认下复制的api_key是否正确
401 签名校验失败 {“message”:”HMAC signature does not match”} 签名验证失败,可能原因有很多。
1. 检查api_key,api_secret 是否正确。
2.检查计算签名的参数host,date,request-line是否按照协议要求拼接。
3. 检查signature签名的base64长度是否正常(正常44个字节)。
403 时钟偏移校验失败 {“message”:”HMAC signature cannot be verified, a valid date or x-date header is required for HMAC Authentication”} 检查服务器时间是否标准,相差5分钟以上会报此错误

时钟偏移校验失败示例:

HTTP/1.1 403 Forbidden
Date: Mon, 22 May 2023 05:44:14 GMT
Content-Length: 116
Content-Type: text/plain; charset=utf-8
{
    "message": "HMAC signature does not match, a valid date or x-date header is required for HMAC Authentication"
}

# 请求参数

在调用业务接口时,都需要在 Http Request Body 中配置以下参数,请求数据均为json字符串。
请求参数示例:

{
    "header": {
        "app_id": "123456",
        "uid": "39769795890"
    },
    "parameter": {
        "chat": {
            "domain": "imagev3",
            "temperature": 0.5,
            "top_k": 4,
            "max_tokens": 2028
        }
    },
    "payload": {
        "message": {
            "text": [
                {
                    "role": "user",
                    "content": "base64",
                    "content_type": "image"
                },
                {
                    "role": "user",
                    "content": "这张图片是什么内容",
                    "content_type": "text"
                }
            ]
        }
    }
}

请求参数说明:

参数名 类型 必传 可选值 描述
header.app_id string 控制台创建应用后获取appid 最大长度:8
header.uid string 非必传字段,用于后续扩展 最大长度:32
parameter.chat object 业务参数 用于上传对话的参数信息
parameter.chat.domain string general (基础版)、imagev3(高级版) 模型版本
1、高级版本效果更优;
2、针对相同图片token计量不同,高级版token为动态计量,图片内容越复杂,token消耗越高。
请根据业务选择
parameter.chat.temperature float 取值范围 (0,1] 核采样阈值,向上调整可以增加结果的随机程度 ,默认值0.5
parameter.chat.top_k int 整数值:1~6,默认值4 从k个中随机选择一个(非等概率)
parameter.chat.max_tokens int 最小值是1, 最大值是8192,默认值2048 回答的tokens的最大长度
parameter.chat.chat_id string 非必传字段,用于后续扩展 用于关联会话chat ,需要保障用户下唯一
payload.message.text json/object/array 用户输入的图片、文本等数据 受Token限制,有效内容不能超过8192Token
  • 单轮交互示例说明: 单轮交互只需要传递一个user角色的数据
[
    // 用户的提问
  	{"role": "user", "content": "xxx", "content_type":"image"}, // 首个必须是图片
    {"role": "user", "content": "你会做什么?"}
]
  • 多轮交互的格式示例: 多轮交互需要将之前的交互历史按照user(image)->user->assistant->user->assistant规则进行拼接,保证最后一条是user的当前问题
[
    // 拼接对话历史信息:
  	{"role": "user", "content": "xxx", "content_type":"image"}, // 首个必须是图片
    {"role": "user", "content": "图片里面有几个人"},              // 用户第一个问题   role是user,表示是用户的提问
    {"role": "assistant", "content": "有三个人"},        // AI的第一个回复  role是assistant,表示是AI的回复

    // 用户最新的提问
    {"role": "user", "content": "几条腿?"}
]

字段参数说明:

字段 含义 数据类型 取值范围 默认值 说明
role 角色 string user, assistant user表示是用户的问题,assistant表示AI的回复
content 文本内容 string -- 该角色的对话内容
  • 图片数据
{
    "role": "user",
    "content": "base64",
    "content_type": "image",
}

字段参数说明:

字段 含义 数据类型 取值范围 默认值 说明
role 角色 string user 多模的数据上传使用user
content 图片的base64数据 string -- 模型自动判断格式,直接传二进制数据即可
content_type 数据的类型 string image、text text 图片上传的时候固定使用image

# 返回结果

返回参数示例:
成功

{
    "header": {
        "code": 0,
        "message": "Success",
        "sid": "cht000704fa@dx16ade44e4d87a1c802",
        "status": 0
    },
    "payload": {
        "choices": {
            "status": 2,
            "seq": 0,
            "text": [
                {
                    "content": "这是AI的回复文本",
  	            "content_type": "text",
      	            "content_meta": {
        	            "desc": "xxxx",
        	            "url": false,
    		            },
                    "index": 0,
                    "role": "assistant"
                }
            ]
        },
        "usage": {
            "text": {
                "completion_tokens": 0,
                "question_tokens": 0,
                "prompt_tokens": 0,
                "total_tokens": 0
            }
        }
    }
}

异常

{
    "header": {
        "code": 10110,     
        "message": "xxxx", 
        "sid": "cht00120013@dx181c8172afb0001102",
        "status": 2,
    }
}

返回参数说明:

参数 类型 含义
header.code int 服务错误码 , 0表示正常,非0表示出错
header.sid string 会话的sid
header.status int 会话的状态,取值[0,1,2], 其中0表示第一个结果, 1表示中间结果, 2表示最后一个结果
header.message string 返回消息描述 ,错误码的描述信息
payload.choices.status int 数据状态 ,0:开始, 1:开始, 2:结束(表示文本响应结束)
payload.choices.seq int 数据序号,最小值:0, 最大值:9999999
payload.choices.text json object array 文本结果 ,是一个json 数组
payload.usage object token消耗响应,最后一个结果时,才会有该字段
payload.usage.text json / object 文本数据
payload.usage.text.completion_tokens int 回答tokens大小
payload.usage.text.question_tokens int 问题不带历史的tokens大小 ,单轮情况下,此数值会略小于prompt_tokens
payload.usage.text.prompt_tokens int 问题总tokens大小
payload.usage.text.total_tokens int 问题和回答的tokens大小

choices字段参数说明

参数 类型 含义
content string 回答的结果
content_type string 数据的类型
index int 结果序号,在多候选中使用
role string 角色,assistant说明这是AI的回复

# 结果格式补充说明

模型结果除了普通文本类型,为了满足排版需求,会出现以下的标记语言,建议集成方进行适配:

  • markdown(表格、列表等)
  • latex(数学公式)

# 错误码描述

错误码 错误信息
0 成功
10003 用户的消息格式有错误
10004 用户数据的schema错误
10005 用户参数值有错误
10006 用户并发错误:当前用户已连接,同一用户不能多处同时连接。
10013 用户问题涉及敏感信息,审核不通过,拒绝处理此次请求。
10022 模型生产的图片涉及敏感信息,审核不通过
10029 图片任何一边的长度超过12800,请检查图片
10041 图片分辨率不符合要求,50×50 < 图片总像素值 < 6000×6000。
10907 token数量超过上限。对话历史+问题的字数太多,需要精简输入。

# 常见问题

# 图片理解的主要功能是什么?

答:用户输入一张图片和问题,从而识别出图片中的对象、场景等信息回答用户的问题。

# 图片理解支持什么应用平台?

答:目前支持Web API应用平台。

# 图片理解的文本大小限制多少?

答:有效内容不能超过8192Token。

在线
咨询
建议
反馈
体验
中心