API Reference

Last Updated: 2024-06-18

Overview

/agent: The agent is a core concept in WeShop AI, representing different agents and tools we have that tailored to your needs. Please refer to https://www.weshop.ai/agent (opens in a new tab) if you need more information. In WeShop AI, users need to select the appropriate agent(s) to start the task. Each agent includes detailed instructions to help users precisely choose the right agent.
- /task: Task module.
  - /create: Create a new task.
  - /execute: Select parameters and execute an existing task.
  - /query: Query task information, such as task status and progress.
  - /delete: Delete an existing task.
- /info: Query specific agent features and information. Please read carefully before using.
/asset: Data asset management (DAM).
- /upload: Upload assets.
  - /image: Upload images.

Please choose the appropriate API according to your needs and follow the documentation for requests. If you have any questions, please email: hi@weshop.ai.

Quick Start

Example

Customer A is developing a series of new fashion clothing and needs to perform commercial photography for the clothing. Follow the steps below to easily complete an ai shooting task by dressing the clothing on a mannequin and taking photos with a phone or camera:

Process

Upload the photos to the resource library and send a request (example) to get the image link.

curl --location 'https://openapi.weshop.ai/openapi/v1/asset/upload/image' \
--header 'Authorization: <API Key>' \
--form 'image=@"/Users/xx/Downloads/model.png"'

Choose the AI Model (aimodel) agent and the corresponding version (agentVersion). Customize the task name (taskName), and use the image link obtained in step 1 (or use an external image link, ensuring the image link is publicly accessible) as a parameter (originalImage) in the request (example). This will create a task and return a task ID (taskId).

curl --location 'https://openapi.weshop.ai/openapi/v1/agent/task/create' \
--header 'Authorization: <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "agentName": "aimodel",
    "agentVersion" : "v1.0",
    "initParams": {
        "taskName": "Create Task Api Test",
        "originalImage": "https://ai-image.weshop.ai/model.png"
    }
}'

Use the task ID from step 2, choose "autoApparelSegment" for automatic apparel segmentation("autoApparelSegment" for automatic subject segmentation or "custom" to manually upload a mask image that meets the requirements), and use the text description content as a parameter (textDescription) in the request (example). This will create a task execution and return an execution ID (executionId).

curl --location 'https://openapi.weshop.ai/openapi/v1/agent/task/execute' \
--header 'Authorization: <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "taskId": "<task id>",
    "params": {
        "generatedContent": "freeCreation",
        "maskType": "autoApparelSegment",
        "textDescription": "A young caucasian woman with highly detailed skin, realistic eyes, natural skin texture, confident expression, standing on the street on a sunny day, bright, summer afternoon, clear focus, high quality, iPhone shot, ultra-realistic."
    }
}'

Use the task query interface, passing the execution ID (executionId) from step 3, to get the status and information of the task execution (example).

curl --location 'https://openapi.weshop.ai/openapi/v1/agent/task/query' \
--header 'Authorization: <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "executionId":"<execution id>"
}'

When the task status is "success," an ai shooting task is completed!

Generic Interfaces for Different AI Agents

The agent is a core concept in WeShop AI, representing different agents and tools we have that tailored to your needs. Please refer to https://www.weshop.ai/agent (opens in a new tab) if you need more information. In WeShop AI, users need to select the appropriate agent(s) to start the task. Each agent includes detailed instructions to help users precisely choose the right agent.

Below is an introduction to the generic interfaces for different AI agents. For detailed usage methods of different agents, please visit the specific agent for more information.

Task

Create Task

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

Pass in the agent name (agentName) and version (agentVersion) to create a new task. Upon successful creation, you will receive a task ID (taskId).

Request Parameters

JSON Format

Parameter Name	Required	Type	Description	Notes
agentName	Yes	string	Agent name, e.g.,"aimodel"	Please refer to the agent page to see supported agents by WeShop AI.
agentVersion	Yes	string	Agent version, e.g., "v1.0"	Please refer to the agent page to see supported agents by WeShop AI.
initParams	No	object	Initial task parameters	Please refer to the agent page for detailed parameter information.

Response Parameters

data

Parameter Name	Required	Type	Description	Notes
taskId	Yes	string	Unique task ID	/

CURL Request Example

curl --location 'https://openapi.weshop.ai/openapi/v1/agent/task/create' \
--header 'Authorization: <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "agentName": "aimodel",
    "agentVersion" : "v1.0",
    "initParams": {
        "taskName": "Create Task Api Test",
        "originalImage": "https://ai-image.weshop.ai/xxxxxxxx.png"
    }
}'

Response Example

{
    "success": true,
    "code":    0,
    "message": "success",
    "data": {
        "taskId": "<task id>"
    }
}

Execute Task

POST https://openapi.weshop.ai/openapi/v1/agent/task/execute

Pass in the task ID (taskId) and execution parameters to execute the task. Upon successful execution, you will receive an execution ID (executionId).

Request Parameters

JSON Format

Parameter Name	Required	Type	Description	Notes
taskId	Yes	string	Task ID from create task response	/
params	Yes	object	Parameters required for task execution	Please refer to the agent page to see supported agents by WeShop AI.
callbackUrl	No	string	Callback URL to receive task status changes	1. Callback content is the same as the query task execution result. 2. The callback interface should receive the message via POST and return "SUCCESS" in the response, otherwise it will retry twice. 3. The callback URL must use a complete path starting with https:// or http://, and ensure the domain and IP are accessible from the public internet. 4. To verify the request origin, you can validate the source IP. The current IP list is: [124.223.169.135、115.159.198.57、124.223.172.233 、118.25.45.195、115.159.56.243]

Response Parameters

data

Parameter Name	Required	Type	Description	Notes
executionId	Yes	string	Task Execution ID, unique identifier	/

CURL Request Example

curl --location 'https://openapi.weshop.ai/openapi/v1/agent/task/execute' \
--header 'Authorization: <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "taskId": "<task id>",
    "params": {
        "generatedContent": "freeCreation",
        "maskType": "autoApparelSegment",
        "locationId": 2093
    }
}'

Response Example

{
    "success": true,
    "code":    0,
    "message": "success",
    "data": {
        "executionId": "<execution id>"
    }
}

Query Task Execution Information

POST https://openapi.weshop.ai/openapi/v1/agent/task/query

Retrieve information and results for a specific task ID (taskId) or execution ID (executionId). If both fields are provided, execution ID (executionId) is prioritized.

Request Parameters

JSON Format

Parameter Name	Required	Type	Description	Notes
executionId	No	string	Task Execution ID	/
taskId	No	string	Task ID	If the taskId parameter is provided, up to 20 recent execution records are returned.

Response Parameters

data

Parameter Name	Required	Type	Description	Notes
agentName	Yes	string	Agent name, e.g., "aimodel"	Please refer to the agent page to see supported agents by WeShop AI.
agentVersion	Yes	string	Agent version, e.g., "v1.0"	Please refer to the agent page to see supported agents by WeShop AI.
initParams	Yes	object	Initial task parameters	Please refer to the agent page for detailed parameter information.
executions	Yes	array[object]	Task Execution ID, unique identifier	Please refer to the agent page for detailed parameter information.

CURL Request Example

curl --location 'https://openapi.weshop.ai/openapi/v1/agent/task/query' \
--header 'Authorization: <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "taskId":"<task id>"
}'

Response Example

{
    "success": true,
    "code": "0",
    "msg": "success",
    "data": {
        "agentName": "aimodel",
        "agentVersion" : "v1.0",
        "initParams": {
            "originalImage": "https://ai-image.weshop.ai/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.ai/xxxxxxxx.png"
                    },
                    {
                        "status": "Success",
                        "image": "https://ai-image.weshop.ai/xxxxxxxx.png"
                    },
                    {
                        "status": "Success",
                        "image": "https://ai-image.weshop.ai/xxxxxxxx.png"
                    },
                    {
                        "status": "Success",
                        "image": "https://ai-image.weshop.ai/xxxxxxxx.png"
                    }
                ]
            },
            {
                "executionId": "<execution id>",
                "executionTime": "2023-11-27 19:25:48",
                "status": "Success",
                "params": {
                    "paramType": "textDescription",
                    "maskType": "autoApparelSegment",
                    "textDescription": "caucasian girl"
                },
                "result": [
                    {
                        "status": "Success",
                        "image": "https://ai-image.weshop.ai/xxxxxxxx.png"
                    },
                    {
                        "status": "Success",
                        "image": "https://ai-image.weshop.ai/xxxxxxxx.png"
                    },
                    {
                        "status": "Success",
                        "image": "https://ai-image.weshop.ai/xxxxxxxx.png"
                    },
                    {
                        "status": "Success",
                        "image": "https://ai-image.weshop.ai/xxxxxxxx.png"
                    }
                ]
            }
        ]
    }
}

Delete Task

POST https://openapi.weshop.ai/openapi/v1/agent/task/delete

Provide the task ID (taskId) to delete the task and its execution records.

Request Parameters

JSON Format

Parameter Name	Required	Type	Description	Notes
taskId	Yes	string	Task ID	/

Response Parameters

None

CURL Request Example

curl --location 'https://openapi.weshop.ai/openapi/v1/agent/task/delete' \
--header 'Authorization: <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "taskId":"<task id>"
}'

Response Example

{
    "success": true,
    "code": "0",
    "msg": "success"
}

Info

Retrieve agent information

GET https://openapi.weshop.ai/openapi/v1/agent/info

Provide the agent name (agentName) and version number (agentVersion) to obtain corresponding configuration parameters.

Request Parameters

JSON Format

Parameter Name	Required	Type	Description	Notes
agentName	Yes	string	Agent name, e.g., "aimodel""aimodel"	Please refer to the agent page to see supported agents by WeShop AI.
agentVersion	Yes	string	Agent version, e.g., "v1.0"	Please refer to the agent page to see supported agents by WeShop AI.

Response Parameters

data

Refer to the specific agent definition.

CURL Request Example

curl --location 'https://openapi.weshop.ai/openapi/v1/agent/info?agentName=aimodel&agentVersion=v1.0' \
--header 'Authorization: <API Key>'

Response Example

{
    "success": true,
    "code": "0",
    "msg": "success",
    "data": {
        "agentVersion": "v1.0",
        "locations": [
            {
                "id": 2113,
                "image": "https://ai-global-image.weshop.com/3e3fe7db-4cac-4c2d-8530-c4d9973b75ae_1024x1024.png_256x256.jpeg",
                "name": "Shopping Mall",
                "categories": ["Commercial Complex"],
                "tags": [
                    {
                        "id": 2034,
                        "name": "Cinematic"
                    },
                    {
                        "id": 2035,
                        "name": "Film Grain"
                    },
 
                    ......
 
                    {
                        "id": 2036,
                        "name": "Spot light"
                    }
                ]
            },
            {
                "id": 2371,
                "image": "https://ai-global-image.weshop.com/9cba7891-dd9f-43ca-875d-1411cf9fd5ed_1024x1024.png_256x256.jpeg",
                "name": "Grocery Store",
                "categories": ["Store"],
                "tags": [
                    {
                        "id": 2012,
                        "name": "Summer"
                    },
                    {
                        "id": 2017,
                        "name": "Fall"
                    },
 
                    ......
 
                    {
                        "id": 2004,
                        "name": "Spring"
                    }
                ]
            }
        ],
        "fashionModels": [
            {
                "id": 20082,
                "image": "https://ai-global-image.weshop.com/92e45b1b-830d-4eaa-8ac2-340fc930230e_560x648.png_crop512.jpeg",
                "name": "Letitia",
                "profile": {
                    "nationality": "Spain",
                    "style": "Mature, Sexy",
                    "priceDescription": "Additional cost of 5 points/image",
                },
                "type": "AI",
                "tags": [
                    {
                        "id": 2003,
                        "name": "Smile"
                    },
                    {
                        "id": 2014,
                        "name": "Elegant"
                    }
                ]
            },
            {
                "id": 20095,
                "image": "https://ai-global-image.weshop.com/a20ec42f-08b6-4b81-a4ea-36ce4a37fd2f_680x1024.png_crop512.jpeg",
                "name": "Eve",
                "profile": {
                    "nationality": "Poland",
                    "style": "Sweet, Cute",
                    "priceDescription": "Additional cost of 5 points/image",
                },
                "type": "AI",
                "tags": [
                    {
                        "id": 2014,
                        "name": "Elegant"
                    },
                    {
                        "id": 2007,
                        "name": "Laughing"
                    },
                    {
                        "id": 2020,
                        "name": "Fashionable"
                    }
                ]
            }
        ]
    }
}

Asset

Asset is a data asset management (DAM) provided by WeShop AI for API users, currently supporting image uploads and retrieval of image links.

Upload

Upload Image

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

Upload an image meeting the requirements to WeShop AI to get the image link.

Request Parameters

form-data format

Parameter Name	Required	Type	Description	Notes
image	Yes	file	Uploaded image	1. Image formats: png, jpeg, jpg, webp 2. Image dimensions: both width and height must be greater than 512 pixels 3. Image aspect ratio must be less than 2 4. Image size must not exceed 10MB

Response Parameters

data

Parameter Name	Required	Type	Description	Notes
image	Yes	string	Image URL	/

CURL Request Example

curl --location 'https://openapi.weshop.ai/openapi/v1/asset/upload/image' \
--header 'Authorization: <API Key>' \
--form 'image=@"/Users/xx/Downloads/image.png"'

Response Example

{
    "success": true,
    "code": "0",
    "msg": "success",
    "data": {
        "image": "<image>"
    }
}

API Key Agent