API Reference #

Note: API endpoints may subject to change without further notice

The WebP Cloud API provides a standardized programmatic interface to access its infrastructure.

To interact with the information available, you can make HTTPS requests to a specific version endpoint URL. The API supports various methods, including GET, POST, PUT, PATCH, and DELETE, which determine how you interact with the data. It’s important to note that all endpoints are accessible only through the SSL-enabled HTTPS protocol on port 443.

API base URL

https://webppt.webp.se

All requests must have the following headers:

Content-Type: application/json
api-key: <Your API Key Here>

User #

Get user info #

GET /v1/user/info

Example response:

{
    "data": {
        "user_uuid": "dc185b97-12af-455b-9337-8356a48bf098",
        "name": "Nova Kwok",
        "email": "nova@nova.moe",
        "avatar_url": "https://avatars.githubusercontent.com/u/24852034?v=4",
        "api_key": "192a7d7f-xxxx-xxxx-xxxx-ff79e7f9f9d6",
        "daily_quota": 0,
        "daily_quota_limit": 10000,
        "permanent_quota": 0,
        "user_plan": "plus"
    },
    "success": true
}

Get user stats #

GET /v1/user/stats

Example response:

{
    "data": {
        "user_uuid": "dc185b97-12af-455b-9337-8356a48bf098",
        "user_total_bytes_sent": 6083487548,
        "user_daily_bytes_sent": [
            {
                "date": "2023-08-18",
                "bytes_sent": 35293558,
                "count": 2009
            },
            {
                "date": "2023-08-19",
                "bytes_sent": 70078770,
                "count": 2146
            },
            {
                "date": "2023-08-20",
                "bytes_sent": 337527554,
                "count": 2649
            },
            {
                "date": "2023-08-21",
                "bytes_sent": 70577230,
                "count": 2050
            },
            {
                "date": "2023-08-22",
                "bytes_sent": 142492032,
                "count": 2028
            },
            {
                "date": "2023-08-23",
                "bytes_sent": 94466746,
                "count": 1905
            },
            {
                "date": "2023-08-24",
                "bytes_sent": 46264580,
                "count": 237
            }
        ]
    },
    "success": true
}

Proxy #

Create proxy #

POST /v1/proxy

Proxy Region

Currently regions are:

Nuremberg (NUE)

Helsinki (HEL) (Currently not available)

Hillsboro,OR (HIO)

Example Payload

{
  "proxy_name": "ECENPAC Proxy",
  "proxy_origin_url": "https://www.ecenpac.com",
  "proxy_region": "NUE"
}

Example response:

{
    "proxy_uuid": "a533df3e-2918-4775-b47b-32b5e0bab296",
    "success": true
}

List all proxies #

GET /v1/proxy

Example response:

{
    "data": [
        {
            "proxy_uuid": "d86f08d1-f29c-4889-8063-431e10e74c8e",
            "proxy_name": "Docs",
            "proxy_origin_url": "https://www.ecenpac.com",
            "proxy_proxy_url": "https://ysjbjsw.webp.ee",
            "proxy_ua": "WebP Cloud Services/1.0",
            "proxy_cors_header": "*",
            "proxy_allowed_referer": "*",
            "proxy_quality": 80,
            "proxy_cache_expire": 0,
            "proxy_cache_size": 9210737,
            "proxy_cache_size_limit": 104857600,
            "proxy_enabled": true,
            "proxy_visual_effects": [
                {
                    "item_uuid": "fac3fbbe-3494-4fe1-9393-dedff4720344",
                    "type": "watermark",
                    "watermark": {
                        "name": "bad for json",
                        "text": "We have 一只 憂鬱的臺灣烏龜。こんにちわ，ガッキー！ 조선말 Tiếng",
                        "font": "sans 12",
                        "width": 0.1,
                        "height": 0.1,
                        "offset_x": 0.22,
                        "offset_y": 0.2,
                        "color": "001489ff",
                        "rotate": 0,
                        "fill": ""
                    }
                },
                {
                    "item_uuid": "aden",
                    "type": "filter",
                    "filter": {
                        "name": "aden"
                    }
                }
            ],
            "proxy_created_at": "2023-08-05T15:26:00Z",
            "proxy_enable_extra_params": true,
            "proxy_region": "NUE"
        }
    ],
    "success": true
}

Get proxy stats #

GET /v1/proxy/<proxy_uuid>/stats

Example response:

{
    "data": {
        "proxy_uuid": "d86f08d1-f29c-4889-8063-431e10e74c8e",
        "proxy_name": "Docs",
        "proxy_origin_url": "https://www.ecenpac.com",
        "proxy_proxy_url": "https://ysjbjsw.webp.ee",
        "proxy_ua": "WebP Cloud Services/1.0",
        "proxy_cors_header": "*",
        "proxy_allowed_referer": "*",
        "proxy_quality": 80,
        "proxy_cache_expire": 0,
        "proxy_cache_size": 9210737,
        "proxy_cache_size_limit": 104857600,
        "proxy_enabled": true,
        "proxy_created_at": "2023-08-05T15:26:00Z",
        "proxy_enable_extra_params": true,
        "proxy_visual_effects": [
            {
                "item_uuid": "fac3fbbe-3494-4fe1-9393-dedff4720344",
                "type": "watermark",
                "watermark": {
                    "name": "bad for json",
                    "text": "We have 一只 憂鬱的臺灣烏龜。こんにちわ，ガッキー！ 조선말 Tiếng",
                    "font": "sans 12",
                    "width": 0.1,
                    "height": 0.1,
                    "offset_x": 0.22,
                    "offset_y": 0.2,
                    "color": "001489C4",
                    "rotate": 0,
                    "fill": ""
                }
            },
            {
                "item_uuid": "aden",
                "type": "filter",
                "filter": {
                    "name": "aden"
                }
            }
        ],
        "proxy_region": "NUE",
        "proxy_total_bytes_sent": 187194,
        "proxy_total_top_requested_path": [
            {
                "requested_path": "/images/create-proxy.png",
                "count": 28,
                "bytes_sent": 138760
            },
            {
                "requested_path": "/images/create-proxy.png?flip=b&visual_effect=filter,name__lofi",
                "count": 1,
                "bytes_sent": 0
            },
            {
                "requested_path": "/images/create-proxy.png?visual_effect=watermark,text__5oiR55qE5LiW55WM5piv5LuA5LmI,width__0.1,height__0.1,offset_x__0.23,offset_y__0.34,font__WenQuanYi%20Zen%20Hei,color__001489",
                "count": 1,
                "bytes_sent": 0
            }
        ],
        "proxy_daily_bytes_sent": [
            {
                "date": "2023-08-02",
                "bytes_sent": 0,
                "count": 0
            },
            {
                "date": "2023-08-03",
                "bytes_sent": 0,
                "count": 0
            },
            {
                "date": "2023-08-04",
                "bytes_sent": 0,
                "count": 0
            },
            {
                "date": "2023-08-05",
                "bytes_sent": 154758,
                "count": 34
            },
            {
                "date": "2023-08-06",
                "bytes_sent": 16032,
                "count": 10
            },
            {
                "date": "2023-08-07",
                "bytes_sent": 16404,
                "count": 4
            },
            {
                "date": "2023-08-08",
                "bytes_sent": 0,
                "count": 0
            }
        ],
        "proxy_last_logs": [
            {
                "created_at": "2023-08-07T02:51:32Z",
                "requested_path": "/images/create-proxy.png?visual_effect=watermark,text__5oiR55qE5LiW55WM5piv5LuA5LmI,width__0.1,height__0.1,offset_x__0.23,offset_y__0.34,color__001489,font__WGlhb2xhaVND",
                "webp_cache_status": "Dynamic",
                "referer": ""
            },
            {
                "created_at": "2023-08-07T02:51:27Z",
                "requested_path": "/images/create-proxy.png?visual_effect=watermark,text__5oiR55qE5LiW55WM5piv5LuA5LmI,width__0.1,height__0.1,offset_x__0.23,offset_y__0.34,color__001489,font__WGlhb2xhaVND",
                "webp_cache_status": "Hit",
                "referer": ""
            }
        ]
    },
    "success": true
}

Edit Proxy #

PUT /v1/proxy/<proxy_uuid>

Example payload:

{
  "proxy_name": "NovaProxy3",
  "proxy_quality": 90,
  "proxy_enabled": true,
  "proxy_ua": "Custom UA",
  "proxy_cors_header": "*",
  "proxy_allowed_referer": "*"
}

proxy_ua is User Agent used when WebP Cloud fetch original image from origin server.
proxy_cors_header is CORS header used when WebP Cloud renders image. Header name: Access-Control-Allow-Origin
proxy_allowed_referer is allowed referer header when WebP Cloud renders image. Setting this other than * will make WebP Cloud check for Referer header, and only allow specified referer to access image. * means allow all referer, to allow multiple domains, use comma serperated hostname, like blog.webp.se,nova.moe,dmesg.app,tuki.moe.

Example response:

{
    "success": true
}

Delete Proxy #

DELETE /v1/proxy/<proxy_uuid>

Example response:

{
    "success": true
}

Purge cache #

Purge all cache under given <proxy_uuid>

POST /v1/proxy/<proxy_uuid>/purge_cache

Example response:

{
    "success": true
}

Clear cache #

Purge cache under given <proxy_uuid> with path

POST /v1/proxy/<proxy_uuid>/clear_cache

Example Payload

{
  "path": "/post/weekly-recap/2023/28-ordinary-days/spirit-toad.jpg"
}

{
    "success": true
}

Visual Effects #

Currently supported visual effects are:

watermark
filter

Create watermark #

POST /v1/visual/watermark

Example Payload

{
  "name": "good",
  "text": "aawae",
  "font": "sans 12",
  "width": 0.1,
  "height": 0.1,
  "offset_x": 0.22,
  "offset_y": 0.2,
  "color": "001489ff",
  "fill": "123456c4"
}

name: Just the name of this watermark preset.
text: Text to be added on image, need to be encoded in base64(url-safe).
font: Font name, currently we support 11 fonts, see below for details
color: Text color, in hex format, w/o transparency
width: Relative text width, in percentage from 0 to 1
height: Relative text height, in percentage from 0 to 1
offset_x: Relative text x position, in percentage from 0 to 1
offset_y: Relative text y position, in percentage from 0 to 1
fill: Fill text background color, in hex format or empty, empty means no fill

All parameters are required.

Supported font list:

Font Name	Parameter name(`font`)
Sans	`sans 12`
Roboto	`Roboto`
Noto Sans	`Noto Sans`
Source Han Sans（思源黑体）	`Source Han Sans HC VF`
wqy-zenhei（文泉驿正黑体）	`WenQuanYi Zen Hei`
FZFangSong-Z02（方正仿宋）	`FZFangSong-Z02`
FZHei-B01（方正黑体）	`FZHei-B01`
FZKai-Z03（方正楷体）	`FZKai-Z03`
FZShuSong-Z01（方正书宋）	`FZShuSong-Z01`
Architects Daughter	`Architects Daughter`
Gloria Hallelujah	`Gloria Hallelujah`
XiaolaiSC（小赖字体）	`XiaolaiSC`
LXGW WenKai(霞鹜文楷)	`LXGW WenKai`

Example response:

{
    "item_uuid": "e8391198-28a9-4a0f-acc8-fd42f3bb0f1e",
    "success": true
}

List Watermark #

GET /v1/visual/watermark

Example response:

{
    "data": [
        {
            "item_uuid": "3f36673b-a002-4b84-8533-021969c85ca1",
            "type": "watermark",
            "watermark": {
                "name": "bad for json",
                "text": "New text for json",
                "font": "sans 12",
                "width": 0.1,
                "height": 0.1,
                "offset_x": 0.22,
                "offset_y": 0.2,
                "color": "001489",
                "rotate": 0,
                "fill": ""
            }
        },
        {
            "item_uuid": "fac3fbbe-3494-4fe1-9393-dedff4720344",
            "type": "watermark",
            "watermark": {
                "name": "bad for json",
                "text": "We have 一只 憂鬱的臺灣烏龜。こんにちわ，ガッキー！ 조선말 Tiếng",
                "font": "sans 12",
                "width": 0.1,
                "height": 0.1,
                "offset_x": 0.22,
                "offset_y": 0.2,
                "color": "001489",
                "rotate": 0,
                "fill": ""
            }
        }
    ],
    "success": true
}

Bind watermark to proxy #

POST /v1/proxy/:proxy_uuid/visual/watermark

Example Payload

{
  "item_uuids": ["cf4ef256-bf0a-4fc8-a3a8-529f283b0db9"]
}

If you passin item_uuids as empty array, it will remove all watermarks from proxy.

Example response:

{
    "success": true
}

Now you can check for proxy info:

{
    "data": [
        {
            "proxy_uuid": "d86f08d1-f29c-4889-8063-431e10e74c8e",
            "proxy_name": "Docs",
            "proxy_origin_url": "https://docs.webp.se",
            "proxy_proxy_url": "https://830368c.webp.ee",
            "proxy_ua": "WebP Cloud Services/1.0",
            "proxy_quality": 80,
            "proxy_cache_expire": 0,
            "proxy_cache_size": 9210737,
            "proxy_cache_size_limit": 104857600,
            "proxy_enabled": true,
            "proxy_visual_effects": [
                {
                    "item_uuid": "fac3fbbe-3494-4fe1-9393-dedff4720344",
                    "type": "watermark",
                    "watermark": {
                        "name": "bad for json",
                        "text": "We have 一只 憂鬱的臺灣烏龜。こんにちわ，ガッキー！ 조선말 Tiếng",
                        "font": "sans 12",
                        "width": 0.1,
                        "height": 0.1,
                        "offset_x": 0.22,
                        "offset_y": 0.2,
                        "color": "001489",
                        "rotate": 0,
                        "fill": ""
                    }
                },
                {
                    "item_uuid": "aden",
                    "type": "filter",
                    "filter": {
                        "name": "aden"
                    }
                }
            ],
            "proxy_created_at": "2023-08-05T15:26:00Z",
            "proxy_enable_extra_params": true,
            "proxy_region": "NUE"
        }
    ],
    "success": true
}

Bind filter to proxy #

POST /v1/proxy/:proxy_uuid/visual/filter

Supported item_uuid are: 1977, aden, brannan, Brooklyn, clarendon, earlybird, gingham, hudson, inkwell, kelvin, lark, lofi, maven, mayfair, moon, nashville, perpetua, reyes, rise, slumber, stinson, toaster, valencia, walden, willow, xpro2

Example Payload

{
  "item_uuids": ["1977"]
}

If you passin item_uuids as empty array, it will remove all filters from proxy.

Example response:

{
    "success": true
}

Delete watermark #

Unbound watermark from all applied proxies, and delete watermark

Delete watermark will remove it from all proxies

DELETE /v1/visual/watermark/:watermark_uuid

Example response:

{
    "success": true
}

Update watermark #

PUT /v1/visual/watermark/:watermark_uuid

Example Payload

{
  "name": "new name really",
  "text": "aawae",
  "font":"sans 12",
  "width": 0.3,
  "height": 0.3,
  "offset_x": 0.3,
  "offset_y": 0.3,
  "color": "121212",
  "fill": ""
}

Example response:

{
    "success": true
}