文档(beta)
API手册

API手册

更新时间:2024-06-07

概述

  • /agent:智能体是WeShop唯象的核心概念,它代表了针对不同用户需求的智能解决方案。在WeShop唯象中,用户的需求都需要通过选择适用的智能体来实现。每个智能体都包含了详细的说明,用户可以根据这些信息来精确选择匹配需求的智能体。
    • /task:任务模块。

      • /create:新建任务。

      • /execute:选择参数、执行已创建任务。

      • /query:查询任务信息,例如任务状态、执行进度等。

      • /delete:删除已创建的任务。

    • /info:用于查询指定智能体的特色信息,请使用前查询并仔细阅读。

  • /asset:轻量级资源管理。
    • /upload:上传资源。

请根据需求选择适合的API,并按照文档说明进行请求。如有疑问,请发送邮件至:develop@weshop.com


快速开始

示例

A品牌客户正在开发一系列全新时尚服饰,需要进行服饰商业拍摄。按照以下示例步骤,只需将服饰穿在人台模特身上,使用手机或摄像机拍摄照片,选择AI模特智能体来轻松完成一次商拍任务:

流程

  1. 将拍摄的照片上传到资源库,获取其图片链接

    curl --location 'https://openapi.weshop.com/openapi/v1/asset/upload/image' \
    --header 'Authorization: <API密钥>' \
    --form 'image=@"/Users/xx/Downloads/人台照片.png"'
  2. 选择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"
        }
    }'
  3. 使用流程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拍摄,超逼真。"
        }
    }'
  4. 使用任务查询接口,将流程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>"
    }'
  5. 当任务执行状态为“成功”,一次轻松的商拍任务完成了!


智能体通用接口

智能体是WeShop唯象的核心概念,它代表了针对不同用户需求的智能解决方案。在WeShop唯象中,用户的需求都需要通过选择适用的智能体来实现。每个智能体都包含了详细的说明,用户可以根据这些信息来精确选择匹配需求的智能体。

下文介绍智能体的通用接口,有关不同智能体的详细使用方法,请访问智能体以获取更多信息。


Task

创建任务

POST https://openapi.weshop.com/openapi/v1/agent/task/create

传入智能体(agentName)和版本(agentVersion),并创建新的任务。创建任务成功后,将收到任务ID(taskId)。

请求参数

  • json格式
参数名必填参数类型描述注意
agentNamestring智能体名称,如:
"aimodel"
请访问智能体查看WeShop唯象支持的智能体信息
agentVersionstring智能体版本,如:
"v1.0"
请访问智能体查看WeShop唯象支持的智能体信息
initParamsobject初始任务参数请访问智能体查看相关智能体信息,以获取参数的详细信息

响应参数

  • data
参数名必填参数类型描述注意
taskIdstring任务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格式
参数名必填参数类型描述注意
taskIdstring创建任务接口的响应/
paramsobject执行任务所需的相关参数请访问智能体查看相关智能体信息,以获取参数的详细信息
callbackUrlstring用于接收任务状态变更的回调URL1. 回调内容与查询任务执行信息返回结果相同。
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
参数名必填参数类型描述注意
executionIdstring任务执行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格式
参数名必填参数类型描述注意
executionIdstring任务执行ID/
taskIdstring任务ID如果传入taskId参数,最多返回近20条执行信息

响应参数

  • data
参数名称必填类型描述注意
agentNamestring智能体名称,如:
"aimodel"
请访问智能体查看WeShop唯象支持的智能体信息
agentVersionstring智能体版本,如:
"v1.0"
请访问智能体查看WeShop唯象支持的智能体信息
initParamsobject初始任务参数请访问智能体查看相关智能体信息,以获取参数的详细信息
executionsarray[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格式
参数名必填参数类型描述注意
taskIdstring任务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格式
参数名必填参数类型描述注意
agentNamestring智能体名称,如:
"aimodel"
请访问智能体查看WeShop唯象支持的智能体信息
agentVersionstring智能体版本,如:
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": 2103,
                "image": "https://ai-image.weshop.com/403df960-8ac8-47c1-bdff-3e90681d855f_1024x1024.png_256x256.jpeg",
                "name": "纯色摄影棚",
                "tags": [
                    {
                        "id": 2034,
                        "name": "电影质感"
                    },
                    {
                        "id": 2035,
                        "name": "胶片颗粒"
                    },
 
                    ......
 
                    {
                        "id": 2036,
                        "name": "聚光灯"
                    }
                ]
            },
            {
                "id": 2093,
                "image": "https://ai-image.weshop.com/7abd3dbb-5c39-47b8-85b9-9477e09425c6.png_256x256.jpeg",
                "name": "街拍",
                "tags": [
                    {
                        "id": 2012,
                        "name": "夏天"
                    },
                    {
                        "id": 2029,
                        "name": "傍晚"
                    },
 
                    ......
 
                    {
                        "id": 2004,
                        "name": "春天"
                    }
                ]
            }
        ],
        "fashionModels": [
            {
                "id": 20002,
                "image": "https://ai-image.weshop.com/683aabd5-7472-425d-aeda-7d3003c08bb5_560x704.png_crop512.jpeg",
                "name": "宝宝",
                "profile": {
                    "nationality": "中国",
                    "style": "优雅/知性",
                    "priceDescription": "额外消耗5算力点/张",
                },
                "tags": [
                    {
                        "id": 2003,
                        "name": "微笑"
                    },
                    {
                        "id": 2006,
                        "name": "气质"
                    }
                ]
            },
            {
                "id": 20090,
                "image": "https://ai-image.weshop.com/7b4612ba-bd60-47d8-937e-c8fe74e42bff_1360x1360.png_crop512.jpeg",
                "name": "笑笑",
                "profile": {
                    "nationality": "中国",
                    "style": "甜美/萝莉",
                    "priceDescription": "额外消耗5算力点/张",
                },
                "tags": [
                    {
                        "id": 2006,
                        "name": "气质"
                    },
                    {
                        "id": 2007,
                        "name": "大笑"
                    },
                    {
                        "id": 2020,
                        "name": "时尚高冷"
                    }
                ]
            }
        ]
    }
}

Asset

Asset是WeShop唯象为API用户提供的轻量资源中心,目前仅支持上传图片和获取图片链接。


Upload

上传图片

POST https://openapi.weshop.com/openapi/v1/asset/upload/image

上传符合要求的图片到WeShop唯象,以获取该图片的链接。

请求参数

  • form-data格式
参数名必填参数类型描述注意
imagefile上传的图片1. 图片格式:png,jpeg,jpg,webp
2. 图片尺寸要求:宽度和高度都必须大于512像素
3. 图片的宽高比小于2
4. 图片的大小不超过10M

响应参数

  • data
参数名必填参数类型描述注意
imagestring图片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": "0",
    "msg": "操作成功",
    "data": {
        "image": "<image>"
    }
}