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) (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_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_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 forReferer
header, and only allow specified referer to access image.*
means allow all referer, to allow multiple domains, use comma serperated hostname, likeblog.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, andhost
,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
}