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
}

Get user metrics #

GET /v1/user/metrics

Example response:

user_bytes_sent_total 197517756
user_daily_quota 649
user_daily_quota_limit 1000
user_permanent_quota 1000

Proxy #

Create proxy #

POST /v1/proxy

Proxy Region

Currently regions are:

Nuremberg (NUE)

Helsinki (HEL)

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_adaptive_resize": false,
            "proxy_adaptive_resize_desktop_width": 1600,
            "proxy_adaptive_resize_mobile_width": 800,
            "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",
            "proxy_extra_headers": [
                {
                    "key": "Header2",
                    "value": "Value2"
                }
            ]
        }
    ],
    "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_adaptive_resize": false,
        "proxy_adaptive_resize_desktop_width": 1600,
        "proxy_adaptive_resize_mobile_width": 800,
        "proxy_total_requests": 1200254,
        "proxy_total_bytes_sent": 187194,
        "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_extra_headers": [
            {
                "key": "Header2",
                "value": "Value2"
            }
        ],
        "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,
                "cache_hit_ratio": 0
            },
            {
                "date": "2023-08-03",
                "bytes_sent": 0,
                "count": 0,
                "cache_hit_ratio": 0
            },
            {
                "date": "2023-08-04",
                "bytes_sent": 0,
                "count": 0,
                "cache_hit_ratio": 0
            },
            {
                "date": "2023-08-05",
                "bytes_sent": 154758,
                "count": 34,
                "cache_hit_ratio": 56
            },
            {
                "date": "2023-08-06",
                "bytes_sent": 16032,
                "count": 10,
                "cache_hit_ratio": 90
            },
            {
                "date": "2023-08-07",
                "bytes_sent": 16404,
                "count": 4,
                "cache_hit_ratio": 90
            },
            {
                "date": "2023-08-08",
                "bytes_sent": 0,
                "count": 0,
                "cache_hit_ratio": 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": ""
            }
        ],
        "proxy_visitor_distribution_7_days": [
            {
                "country": "US",
                "count": 4092383
            },
            ...
            {
                "country": "BN",
                "count": 1
            }
        ],
        "proxy_visitor_distribution_30_days": [
            {
                "country": "US",
                "count": 33112416
            },
            ...
            {
                "country": "ET",
                "count": 1
            }
        ],
        "proxy_custom_domain": [
            {
                "custom_domain_uuid": "a05e5c51-44da-4352-9c53-db8dd7fb3ef3",
                "status": "pending",
                "proxy_proxy_url": "some-webp.nova.moe",
                "verification_errors": "",
                "ownership_verification_key": "_cf-custom-hostname.some-webp.nova.moe",
                "ownership_verification_value": "3b92ab3e-380b-47f5-9d0b-c1c74827232e",
                "dcv_delegation_record_key": "_acme-challenge.some-webp.nova.moe",
                "dcv_delegation_record_value": "UsWBs_67LRMsvTJBz1Ex_IO3li-mXDAmpo0rmwdiKGY"
            }
        ]
    },
    "success": true
}

Get proxy metrics #

GET /v1/proxy/<proxy_uuid>/metrics

Example response:

proxy_requests_total{cache_status="all"} 154
proxy_requests_total{cache_status="hit"} 48
proxy_bytes_sent_total 65839252
proxy_cache_size 2956337
proxy_cache_size_limit 3480000

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_adaptive_resize": false,
  "proxy_adaptive_resize_desktop_width": 1600,
  "proxy_adaptive_resize_mobile_width": 800,
  "proxy_extra_headers": [
        {
            "key": "Header2",
            "value": "Value2"
        }
    ],
}

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.
proxy_extra_headers is extra headers to be added when WebP Cloud fetch original image from origin server, currently max 5 headers are allowed, the key and value are both string length less than 100, and host, referer,origin header is not allowed.

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"
}

Example response:

{
    "success": true
}

Create custom domain for Proxy #

POST /v1/proxy/<proxy_uuid>/custom_domain

Example Payload

{
  "proxy_proxy_url": "some-webp.nova.moe"
}

Example response:

{
    "success": true
}

After creation, you can refer to /v1/proxy/<proxy_uuid>/stats API for detailed DNS setup instructions, for example for a proxy located at NUE region:

...
"proxy_custom_domain": [
    {
        "custom_domain_uuid": "a05e5c51-44da-4352-9c53-db8dd7fb3ef3",
        "status": "pending",
        "proxy_proxy_url": "some-webp.nova.moe",
        "verification_errors": "",
        "ownership_verification_key": "_cf-custom-hostname.some-webp.nova.moe",
        "ownership_verification_value": "3b92ab3e-380b-47f5-9d0b-c1c74827232e",
        "dcv_delegation_record_key": "_acme-challenge.some-webp.nova.moe",
        "dcv_delegation_record_value": "UsWBs_67LRMsvTJBz1Ex_IO3li-mXDAmpo0rmwdiKGY"
    }
]
...

In the example above you should create the following DNS records:

CNAME
- some-webp.nova.moe
- to
- lb.webp.ee (As the region is NUE, read more at Custom Domain)
TXT
- _cf-custom-hostname.some-webp.nova.moe
- with value of
- 3b92ab3e-380b-47f5-9d0b-c1c74827232e
TXT
- _acme-challenge.some-webp.nova.moe
- with value of
- UsWBs_67LRMsvTJBz1Ex_IO3li-mXDAmpo0rmwdiKGY

Confirm custom domain status #

Once successfully added DNS records, you can use this Endpoint to check if confirm that your DNS is setup, then our system will tries to validate your setup.

GET /v1/proxy/<proxy_uuid>/custom_domain

Example response:

{
    "success": true
}

After confirm, please allow sometime for our side to check, should be within minutes, but can be as long as 24hrs for DNS to propagate, you should refer to /v1/proxy/<proxy_uuid>/stats API for proxy_custom_domain’s status, if it’s active, you’re ready to activate it.

Activate custom domain #

Once the proxy_custom_domain is active, you can activate your custom domain using:

GET /v1/proxy/<proxy_uuid>/custom_domain/activate

Example response:

{
    "success": true
}

This endpoint will change your current proxy_proxy_url to your proxy_custom_domain’s proxy_proxy_url(your custom domain), and proxy_custom_domain’s status will become activated.

Delete custom domain for Proxy #

This endpoint will remove your current custom domain and generate a new domain for you proxy.

DELETE /v1/proxy/<proxy_uuid>/custom_domain

Example response:

{
    "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
}