文档（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格式
参数名必填参数类型描述注意
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用于接收任务状态变更的回调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
参数名必填参数类型描述注意
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": 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格式
参数名必填参数类型描述注意
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"'

响应示例

API密钥智能体