Doc (beta)
API Reference

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.

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

  1. 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"'

  2. 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"
    }
}'

  3. 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."
    }
}'

  4. 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>"
}'

  5. 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 NameRequiredTypeDescriptionNotes
agentNameYesstringAgent name, e.g.,"aimodel"
Please refer to the agent page to see supported agents by WeShop AI.
agentVersionYesstringAgent version, e.g., "v1.0"Please refer to the agent page to see supported agents by WeShop AI.
initParamsNoobjectInitial task parametersPlease refer to the agent page for detailed parameter information.

Response Parameters

  • data
Parameter NameRequiredTypeDescriptionNotes
taskIdYesstringUnique 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 NameRequiredTypeDescriptionNotes
taskIdYesstringTask ID from create task response/
paramsYesobjectParameters required for task executionPlease refer to the agent page to see supported agents by WeShop AI.
callbackUrlNostringCallback URL to receive task status changes1. 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: [43.130.78.160、43.130.74.139、43.130.153.150、43.166.139.136、43.166.240.2]

Response Parameters

  • data
Parameter NameRequiredTypeDescriptionNotes
executionIdYesstringTask 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": 2002093
    }
}'

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 NameRequiredTypeDescriptionNotes
executionIdNostringTask Execution ID/
taskIdNostringTask IDIf the taskId parameter is provided, up to 20 recent execution records are returned.

Response Parameters

  • data
Parameter NameRequiredTypeDescriptionNotes
agentNameYesstringAgent name, e.g., "aimodel"Please refer to the agent page to see supported agents by WeShop AI.
agentVersionYesstringAgent version, e.g., "v1.0"Please refer to the agent page to see supported agents by WeShop AI.
initParamsYesobjectInitial task parametersPlease refer to the agent page for detailed parameter information.
executionsYesarray[object]Task Execution ID, unique identifierPlease 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 NameRequiredTypeDescriptionNotes
taskIdYesstringTask 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 NameRequiredTypeDescriptionNotes
agentNameYesstringAgent name, e.g., "aimodel""aimodel"Please refer to the agent page to see supported agents by WeShop AI.
agentVersionYesstringAgent 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": 6000372,
                "image": "https://ai-global-image.weshop.com/b58e3c41-e7c3-4101-9c7c-ee2847b7c491_728x1088.png",
                "name": "White Studio",
                "categories": ["womenswear"],
                "tags": [
                    {
                        "id": 1002035,
                        "name": "Film grain"
                    },
 
                    ......
 
                    {
                        "id": 1002036,
                        "name": "Spot light"
                    }
                ]
            },
            {
                "id": 6000392,
                "image": "https://ai-global-image.weshop.com/c8da5b9d-51c6-47a5-a41e-19328528e0ca_552x832.png",
                "name": "French Flagstone Pavement",
                "categories": ["menswear"],
                "tags": [
                    {
                        "id": 1002035,
                        "name": "Film grain"
                    },
 
                    ......
 
                    {
                        "id": 1002036,
                        "name": "Spot light"
                    }
                ]
            }
        ],
				"fashionModels": [
            {
                "id": 4020082,
                "image": "https://ai-global-image.weshop.com/ebcdbdcf-be9c-463b-bcd9-bebcf058b112_763x763.png",
                "name": "Letitia",
                "profile": {
                    "nationality": "Spain",
                    "priceDescription": "Additional cost of 5 points / image",
                    "style": "Chic, Sexy, Sophisticated"
                },
                "tags": [
                    {
                        "id": 1002003,
                        "name": "Smiling"
                    },
 
                    ......
 
                    {
                        "id": 1002032,
                        "name": "Lying"
                    }
                ],
                "type": "AI"
            },
 
            ......
 
            {
                "id": 4020095,
                "image": "https://ai-global-image.weshop.com/a20ec42f-08b6-4b81-a4ea-36ce4a37fd2f_680x1024.png",
                "name": "Eve",
                "profile": {
                    "nationality": "Poland",
                    "priceDescription": "Additional cost of 5 points / image",
                    "style": "Sweet, Cute"
                },
                "tags": [
                    {
                        "id": 1002003,
                        "name": "Smiling"
                    },
 
                    ......
 
                    {
                        "id": 1002020,
                        "name": "Fashionable"
                    }
                ],
                "type": "AI"
            }
				]
}

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 NameRequiredTypeDescriptionNotes
imageYesfileUploaded image1. 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 NameRequiredTypeDescriptionNotes
imageYesstringImage 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 KeyAgent