API手册
更新时间:2024-06-07
概述
- /agent:智能体是WeShop唯象的核心概念,它代表了针对不同用户需求的智能解决方案。在WeShop唯象中,用户的需求都需要通过选择适用的智能体来实现。每个智能体都包含了详细的说明,用户可以根据这些信息来精确选择匹配需求的智能体。
- /asset:轻量级资源管理。
- /upload:上传资源。
- /image:上传图片。
- /upload:上传资源。
请根据需求选择适合的API,并按照文档说明进行请求。如有疑问,请发送邮件至:develop@weshop.com。
快速开始
示例
A品牌客户正在开发一系列全新时尚服饰,需要进行服饰商业拍摄。按照以下示例步骤,只需将服饰穿在人台模特身上,使用手机或摄像机拍摄照片,选择AI模特智能体来轻松完成一次商拍任务:
流程
-
将拍摄的照片上传到资源库,获取其图片链接。
curl --location 'https://openapi.weshop.com/openapi/v1/asset/upload/image' \ --header 'Authorization: <API密钥>' \ --form 'image=@"/Users/xx/Downloads/人台照片.png"'
-
选择AI模特(aimodel)智能体和相应的版本(agentVersion),可自定义任务名称(taskName),将流程1中获得的图片链接(也可省略流程1,直接使用外部图片链接,须确保图片链接公网可访问)作为参数(originalImage)传入请求(示例)。这将创建一个任务并返回一个任务ID(taskId)。
curl --location 'https://openapi.weshop.com/openapi/v1/agent/task/create' \ --header 'Authorization: <API密钥>' \ --header 'Content-Type: application/json' \ --data '{ "agentName": "aimodel", "agentVersion" : "v1.0", "initParams": { "taskName": "Create Task Api Test", "originalImage": "https://ai-image.weshop.com/人台照片.png" } }'
-
使用流程2中的任务ID,选择蒙版类型为"autoApparelSegment"自动服饰分割(也可选择"autoApparelSegment"自动主体分割或者"custom"手动上传符合要求的蒙版图像)。将文字描述内容作为参数(textDescription)传入请求(示例)。这将创建一个任务执行,并返回一个任务执行ID(executionId)。
curl --location 'https://openapi.weshop.com/openapi/v1/agent/task/execute' \ --header 'Authorization: <API密钥>' \ --header 'Content-Type: application/json' \ --data '{ "taskId": "<task id>", "params": { "generatedContent": "freeCreation", "maskType": "autoApparelSegment", "textDescription": "一位年轻的中国女性,高度细致的皮肤,逼真的细节眼睛,自然的皮肤纹理,自信的表情,站在街头,晴天,阳光,明亮,夏日午后,清晰对焦,高品质,iPhone拍摄,超逼真。" } }'
-
使用任务查询接口,将流程3获得的任务执行ID(executionId)传入接口(示例),以获取任务执行的状态和信息。
curl --location 'https://openapi.weshop.com/openapi/v1/agent/task/query' \ --header 'Authorization: <API密钥>' \ --header 'Content-Type: application/json' \ --data '{ "executionId":"<execution id>" }'
-
当任务执行状态为“成功”,一次轻松的商拍任务完成了!
智能体通用接口
智能体是WeShop唯象的核心概念,它代表了针对不同用户需求的智能解决方案。在WeShop唯象中,用户的需求都需要通过选择适用的智能体来实现。每个智能体都包含了详细的说明,用户可以根据这些信息来精确选择匹配需求的智能体。
下文介绍智能体的通用接口,有关不同智能体的详细使用方法,请访问智能体以获取更多信息。
Task
创建任务
POST https://openapi.weshop.com/openapi/v1/agent/task/create
传入智能体(agentName)和版本(agentVersion),并创建新的任务。创建任务成功后,将收到任务ID(taskId)。
请求参数
- json格式
参数名 | 必填 | 参数类型 | 描述 | 注意 |
---|---|---|---|---|
agentName | 是 | string | 智能体名称,如: "aimodel" | 请访问智能体查看WeShop唯象支持的智能体信息 |
agentVersion | 是 | string | 智能体版本,如: "v1.0" | 请访问智能体查看WeShop唯象支持的智能体信息 |
initParams | 否 | object | 初始任务参数 | 请访问智能体查看相关智能体信息,以获取参数的详细信息 |
响应参数
- data
参数名 | 必填 | 参数类型 | 描述 | 注意 |
---|---|---|---|---|
taskId | 是 | string | 任务ID 唯一标识 | / |
curl请求示例
curl --location 'https://openapi.weshop.com/openapi/v1/agent/task/create' \
--header 'Authorization: <API密钥>' \
--header 'Content-Type: application/json' \
--data '{
"agentName": "aimodel",
"agentVersion" : "v1.0",
"initParams": {
"taskName": "Create Task Api Test",
"originalImage": "https://ai-image.weshop.com/xxxxxxxx.png"
}
}'
响应示例
{
"success": true,
"code": 0,
"message": "操作成功",
"data": {
"taskId": "<task id>"
}
}
执行任务
POST https://openapi.weshop.com/openapi/v1/agent/task/execute
传入任务的taskId和执行参数信息,进行任务执行。成功执行后,将收到任务执行ID(executionId)。
请求参数
- json格式
参数名 | 必填 | 参数类型 | 描述 | 注意 |
---|---|---|---|---|
taskId | 是 | string | 创建任务接口的响应 | / |
params | 是 | object | 执行任务所需的相关参数 | 请访问智能体查看相关智能体信息,以获取参数的详细信息 |
callbackUrl | 否 | string | 用于接收任务状态变更的回调URL | 1. 回调内容与查询任务执行信息返回结果相同。 2. 回调接口应以POST方式接收消息,并在响应中返回"SUCCESS",否则将进行两次重试通知。 3. 回调URL必须使用完整的 https:// 或http:// 开头的路径地址,并确保域名和IP可从外网访问。 4. 为了确定请求是否来自WeShop唯象官方,目前可以通过验证请求来源IP进行判断,现阶段IP列表为:[124.223.169.135、115.159.198.57、124.223.172.233 、118.25.45.195、115.159.56.243] |
响应参数
- data
参数名 | 必填 | 参数类型 | 描述 | 注意 |
---|---|---|---|---|
executionId | 是 | string | 任务执行ID 唯一标识 | / |
curl请求示例
curl --location 'https://openapi.weshop.com/openapi/v1/agent/task/execute' \
--header 'Authorization: <API密钥>' \
--header 'Content-Type: application/json' \
--data '{
"taskId": "<task id>",
"params": {
"generatedContent": "freeCreation",
"maskType": "autoApparelSegment",
"locationId": 2002093
}
}'
响应示例
{
"success": true,
"code": 0,
"message": "操作成功",
"data": {
"executionId": "<execution id>"
}
}
查询任务执行信息
POST https://openapi.weshop.com/openapi/v1/agent/task/query
传入特定任务ID(taskId)或执行ID(executionId)的相关信息和结果。如果同时传入两个字段,优先选择执行ID(executionId)。
请求参数
- json格式
参数名 | 必填 | 参数类型 | 描述 | 注意 |
---|---|---|---|---|
executionId | 否 | string | 任务执行ID | / |
taskId | 否 | string | 任务ID | 如果传入taskId参数,最多返回近20条执行信息 |
响应参数
- data
参数名称 | 必填 | 类型 | 描述 | 注意 |
---|---|---|---|---|
agentName | 是 | string | 智能体名称,如: "aimodel" | 请访问智能体查看WeShop唯象支持的智能体信息 |
agentVersion | 是 | string | 智能体版本,如: "v1.0" | 请访问智能体查看WeShop唯象支持的智能体信息 |
initParams | 是 | object | 初始任务参数 | 请访问智能体查看相关智能体信息,以获取参数的详细信息 |
executions | 是 | array[object] | 执行信息记录 | 请访问智能体查看相关智能体信息,以获取参数的详细信息 |
curl请求示例
curl --location 'https://openapi.weshop.com/openapi/v1/agent/task/query' \
--header 'Authorization: <API密钥>' \
--header 'Content-Type: application/json' \
--data '{
"taskId":"<task id>"
}'
响应示例
{
"success": true,
"code": "0",
"msg": "操作成功",
"data": {
"agentName": "aimodel",
"agentVersion" : "v1.0",
"initParams": {
"originalImage": "https://ai-image.weshop.com/xxxxxxxx.png",
"taskName": "Create Task Api Test"
},
"executions": [
{
"executionId": "<execution id>",
"executionTime": "2023-11-27 18:51:35",
"status": "Success",
"params": {
"paramType": "textDescription",
"maskType": "autoApparelSegment",
"textDescription": "1girl"
},
"result": [
{
"status": "Success",
"image": "https://ai-image.weshop.com/xxxxxxxx.png"
},
{
"status": "Success",
"image": "https://ai-image.weshop.com/xxxxxxxx.png"
},
{
"status": "Success",
"image": "https://ai-image.weshop.com/xxxxxxxx.png"
},
{
"status": "Success",
"image": "https://ai-image.weshop.com/xxxxxxxx.png"
}
]
},
{
"executionId": "<execution id>",
"executionTime": "2023-11-27 19:25:48",
"status": "Success",
"params": {
"paramType": "textDescription",
"maskType": "autoApparelSegment",
"textDescription": "asian girl"
},
"result": [
{
"status": "Success",
"image": "https://ai-image.weshop.com/xxxxxxxx.png"
},
{
"status": "Success",
"image": "https://ai-image.weshop.com/xxxxxxxx.png"
},
{
"status": "Success",
"image": "https://ai-image.weshop.com/xxxxxxxx.png"
},
{
"status": "Success",
"image": "https://ai-image.weshop.com/xxxxxxxx.png"
}
]
}
]
}
}
删除任务
POST https://openapi.weshop.com/openapi/v1/agent/task/delete
传入任务ID(taskId),即可删除该任务及其执行记录。
请求参数
- json格式
参数名 | 必填 | 参数类型 | 描述 | 注意 |
---|---|---|---|---|
taskId | 是 | string | 任务Id | / |
响应参数
无
curl请求示例
curl --location 'https://openapi.weshop.com/openapi/v1/agent/task/delete' \
--header 'Authorization: <API密钥>' \
--header 'Content-Type: application/json' \
--data '{
"taskId":"<task id>"
}'
响应示例
{
"success": true,
"code": "0",
"msg": "操作成功"
}
Info
查询智能体相关信息
GET https://openapi.weshop.com/openapi/v1/agent/info
传入智能体名称(agentName)和版本号(agentVersion),获得相应的配置参数信息。
请求参数
- json格式
参数名 | 必填 | 参数类型 | 描述 | 注意 |
---|---|---|---|---|
agentName | 是 | string | 智能体名称,如: "aimodel" | 请访问智能体查看WeShop唯象支持的智能体信息 |
agentVersion | 是 | string | 智能体版本,如: v1.0" | 请访问智能体查看WeShop唯象支持的智能体信息 |
响应参数
- data
请查看具体智能体的定义
curl请求示例
curl --location 'https://openapi.weshop.com/openapi/v1/agent/info?agentName=aimodel&agentVersion=v1.0' \
--header 'Authorization: <API密钥>'
响应示例
{
"success": true,
"code": "0",
"msg": "操作成功",
"data": {
"agentVersion": "v1.0",
"locations": [
{
"id": 6000509,
"image": "https://ai-image.weshop.com/3b930afb-b1db-4999-989a-aa9db0663240_1056x1416.png",
"name": "绿植角落",
"categories": ["室内"],
"tags": [
{
"id": 1002034,
"name": "电影质感"
},
......
{
"id": 1002036,
"name": "聚光灯"
}
]
},
{
"id": 6000456,
"image": "https://ai-image.weshop.com/23f94939-cd2e-455b-8ff0-903afe10742d_1248x1680.png",
"name": "阁楼咖啡馆",
"categories": ["室内"],
"tags": [
{
"id": 1002004,
"name": "春天"
},
......
{
"id": 1002036,
"name": "聚光灯"
}
]
}
],
"fashionModels": [
{
"id": 4020002,
"image": "https://ai-image.weshop.com/b351ddc6-396d-46b2-bf22-e629ddcadae9_935x935.png",
"name": "然然",
"profile": {
"nationality": "中国",
"priceDescription": "额外消耗5算力点/张",
"style": "文艺清冷"
},
"tags": [
{
"id": 1002003,
"name": "微笑"
},
......
{
"id": 1002020,
"name": "时尚高冷"
}
],
"type": "AI"
},
{
"id": 4020241,
"image": "https://ai-image.weshop.com/9ec5a001-0dc4-409c-bf76-399f515a48a1_560x560.png",
"name": "秋秋",
"profile": {
"nationality": "中国",
"priceDescription": "额外消耗5算力点/张",
"style": "文艺清冷"
},
"tags": [
{
"id": 1002003,
"name": "微笑"
},
......
{
"id": 1002020,
"name": "时尚高冷"
}
],
"type": "AI"
}
]
}
}
Asset
Asset是WeShop唯象为API用户提供的轻量资源中心,目前仅支持上传图片和获取图片链接。
Upload
上传图片
POST https://openapi.weshop.com/openapi/v1/asset/upload/image
上传符合要求的图片到WeShop唯象,以获取该图片的链接。
请求参数
- form-data格式
参数名 | 必填 | 参数类型 | 描述 | 注意 |
---|---|---|---|---|
image | 是 | file | 上传的图片 | 1. 图片格式:png,jpeg,jpg,webp 2. 图片尺寸要求:宽度和高度都必须大于512像素 3. 图片的宽高比小于2 4. 图片的大小不超过10M |
响应参数
- data
参数名 | 必填 | 参数类型 | 描述 | 注意 |
---|---|---|---|---|
image | 是 | string | 图片URL | / |
curl请求示例
curl --location 'https://openapi.weshop.com/openapi/v1/asset/upload/image' \
--header 'Authorization: <API密钥>' \
--form 'image=@"/Users/xx/Downloads/图片.png"'
响应示例
{
"success": true,
"code": "1001",
"msg": "操作成功",
"data": {
"image": "https://ai-image.weshop.com/xxxxxx.png"
}
}