AI视觉平台openapi-V1 接口文档

概述

这里是关于AI视觉平台API接口说明。

更新日志

接口地址

• 生产环境: https://api.example.com
• 测试环境: https://api.example-test.com

请求基础

头部信息

所有请求都需要在HTTP头部包含以下信息：

错误码

接口列表

万物识别 [POST]

URL

/api/rec-everything

请求参数

⚠️ url 和 bytes 必须有一个非空。

请求示例

{
  "sn": "6615572811fc410c9c68170386961fcd_20260310060250",
  "images": [
    {
      "url": "https://example.com/image.jpg",
      "bytes": "base64_encoded_string",
      "id": "10000",
      "originId": "",
      "fino": false,
      "type": ["tags", "describe"],
      "lang": "zh",
      "familyId":"10001"
    }
  ],
  "minObjectConfidence": 50
}

响应数据

// 成功
{
	"sn": "123456",
	"results": [
		{
			"imageId": "10000",
			"error": "",
			"tags": [
				{
					"name": "person",
					"confidence": 85
				},
				{
					"name": "tree",
					"confidence": 76
				}
			],
			"describe": "一个人站在公园里，周围有树木和草地。",
			"downloadCostMs": 120,
			"engineCostMs": 180
		}
	],
	"costMs": 300,
	"serverSn": "srv_12345"
}

// 失败
{
  "status": 400,
  "message": "请求参数错误"
}

万物识别 -视频[POST]

URL

/api/rec-everything-video

请求参数

⚠️ url 和 bytes 必须有一个非空。

请求示例

{
  "sn": "123456",
  "videos": [
    {
      "url": "https://example.com/video.mp4",
      "bytes": "base64_encoded_string",
      "id": "10000",
      "originId": "",
      "type": ["tags", "describe"],
      "lang": "zh"
    }
  ],
  "minObjectConfidence": 50,
  "combine": 1
}

响应数据

// 成功
{
	"sn": "123456",
	"results": [
		{
			"id": "10000",
			"error": "",
			"tags": [
				{
					"name": "person",
					"confidence": 85
				},
				{
					"name": "tree",
					"confidence": 76
				}
			],
			"describe": "一个人站在公园里，周围有树木和草地。",
			"downloadCostMs": 120,
			"engineCostMs": 180
		}
	],
	"costMs": 300,
	"serverSn": "srv_12345"
}

// 失败
{
  "status": 400,
  "message": "请求参数错误"
}

鸟类识别 [POST]

URL

/api/bird_rec

请求参数

⚠️ url 和 bytes 必须有一个非空。

请求示例

{
	"sn": "12345",
	"lang": "en",
	"images": [
		{
			"id": "10000",
			"bytes": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ...",
             "originId": "",
			"url": ""
		}
	],
	"birdDetConf": 25,
	"squDetConf": 25
}

响应数据

响应示例

// 成功
{
  "sn": "123456",
  "results": [
    {
      "imageId": "10000",
      "error": "",
      "category": {
                "en": "bird",
                "zh": "鸟"
      },
      "detScore": 97.62,
      "downloadCostMs": 90,
      "engineCostMs": 150
    }
  ],
  "costMs": 240,
  "serverSn": "srv_0001"
}

// 失败
{
  "status": 400,
  "message": "请求参数错误"
}

野生动物识别 [POST]

URL

/api/wild_animals_rec

请求参数

⚠️ url 和 bytes 必须有一个非空。

请求示例

{
  "sn": "wild_req_001",
  "lang": "zh",
  "animalDetConf": 20,
  "personDetConf": 50,
  "images": [
    {
      "url": "https://example.com/wildlife.jpg",
      "bytes": "base64_encoded_string",
      "id": "img_wild_001"
    }
  ]
}

响应数据

响应示例

// 成功
{
  "sn": "wild_req_001",
  "results":[
    {
      "imageId": "test2",
      "error": "",
      "category": {
        "la": "Antilocapra americana",
        "zh": "叉角羚"
      },
      "detScore": 95.9,
      "categoryScore": 93.83,
      "downloadCostMs": 2,
      "engineCostMs": 29
    }
  ],
  "costMs": 270,
  "serverSn": "srv_wild_901"
}

// 失败
{
  "status": 400,
  "message": "请求参数错误"
}

宠物识别 [POST]

URL

/api/detect-pet-action

请求参数

请求示例

{
	"sn": "123456",
	"originId": "abc123",
	"lang": "en",
	"videos": [
		{
			"url": "http://xxxx",
			"id": "123456"
		}
	],
	"notifyUrl": "http://xx"
}

响应数据

响应示例

// 成功
{
	"sn": "xxx",
	"results": [
		{
			"videoId": "",
			"error": "",
			"objects": [
				{
					"name": "cat"
				}
			],
			"actions": [
				{
					"name": "lie"
				}
			],
			"description": "a cat is lying in a cat bed.",
			"downloadCostMs": 100,
			"engineCostMs": 100
		}
	],
	"costMs": 300,
	"serverSn": "xxx"
}

// 失败
{
  "status": 400,
  "message": "请求参数错误"
}

异步模式的结果推送

应用端在接收到此响应后，服务端会在未来一段时间内以sn为关联键将结果(与同步模式响应相同)推送(POST)到notifyUrl指定的地址， 该地址应响应200代码，服务端将最多尝试3次推送，间隔10秒，如果失败则将结果丢弃

视频描述 [POST]

URL

/api/video_describe

请求参数

请求示例

{
    "sn": "12345",
	"lang": "en",
	"video": {
		"id": "1234567",
      	"url": "https://example.com/wildlife.jpg",
      	"bytes": "base64_encoded_string"
	}
}

响应数据

响应示例

// 成功
{
  "id" : "123456",
  "results" : "画面中未出现人物，因此无法提供关于人物穿着、动作、意图及互动情况的描述。  \n**场景描述**：画面呈现的是一个室内空间（可能为等候区、休息区或会议室），背景为大面积玻璃窗，窗外可见高楼建筑和少量绿植。室内靠窗位置摆放有黑色座椅，座椅旁似乎有垂挂的装饰物（如珠链），前景中隐约可见深色的桌面边缘。整体画面呈现重复排列的视觉效果，可能是监控画面的多帧连续截图拼接。",
  "inputToken" : 1682,
  "outputToken" : 111,
  "error" : " ",
  "sn" : "12345678",
  "serverSn" : "beijing-volcengine",
  "costMs" : 1002
}

// 失败
{
  "status": 400,
  "message": "请求参数错误"
}

chat大模型 [POST]

URL

/api/chat_completion

头部信息

所有请求都需要在HTTP头部包含以下信息：

请求参数

注意

文本内容必须上传，图片和视频不能同时上传，并且一次只能传一份图片或者视频。model当前使用ivsign-l

请求示例

{
  "model": "ivsign-l",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "<用户文本输入>"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "<图片1的 URL 或 base64 data URL>"
          }
        },
        {
          "type": "video_url",
          "video_url": {
            "url": "<视频的 URL 或 base64 data URL>"
          }
        }
      ]
    }
  ],
  "max_tokens": 512,
  "temperature": 0.3,
  "top_p": 0.9,
  "stop": null,
  "top_k": 0,
  "min_p": 0
}

响应数据

响应示例

// 成功
{
    "status": "200",
    "message": "SUCCESSFUL",
    "data": {
        "id": "chatcmpl_2225d86c",
        "object": "chat.completion",
        "created": 1762584866,
        "dateTime": "2025-11-08 14:54:26",
        "model": "ivsign-l",
        "error": null,
        "choices": [
            {
                "index": 0,
                "message": {
                    "role": "assistant",
                    "content": "This is an image of a Blue Jay, a bird known for its vibrant blue and white plumage"
                },
                "finish_reason": "stop"
            }
        ]
    }
}

// 失败
{
  "status": "400",
  "message": "XXX"
}

人脸库接口

保存/更新家庭成员信息 [POST]

URL

api/face/save

请求参数

请求示例

{
    "memberId":"10001",
    "memberName":"男主人",
    "familyId":"100001",
    "faceImage":"/9j/4AAQSkZJRgABAQAAAQABAAD/4gIoSUNDX1BST0ZJTEUAAQEAAAIYAA...."
}

响应数据

// 成功
{
  "status": 200,
  "message": "success"
}

// 失败
{
  "status": 400,
  "message": "请求参数错误"
}
{
  "status": 402,
  "message": "未检测到人脸"
}

查询家庭成员信息 [POST]

URL

api/face/query

请求参数

请求示例

{
    "familyId":"100001"
}

响应数据

// 成功
{
	"status": 200,
	"message": "success",
	"members": [
		{
			"memberId": "10001",
			"memberName": "男主人",
			"familyId": "100001",
			"faceImage": "/9j/4AAQSkZJRgABAQAAAQABAAD/4gIoSUNDX1BST0ZJTEUAAQEAAAIYAA...."
		},
		{
			"memberId": "10002",
			"memberName": "女主人",
			"familyId": "100001",
			"faceImage": "/9j/4AAQSkZJRgABAQAAAQABAAD/4gIoSUNDX1BST0ZJTEUAAQEAAAIYAA...."
		}
	]
}

// 失败
{
  "status": 400,
  "message": "请求参数错误"
}

删除家庭成员信息 [POST]

URL

api/face/delete

请求参数

请求示例

{
    "memberId":"10001",
    "familyId":"100001"
}

响应数据

// 成功
{
  "status": 200,
  "message": "success"
}

// 失败
{
  "status": 400,
  "message": "请求参数错误"
}