通過 URL 訪問圖片時,對圖片進行處理,并把處理后的圖片返回。
URL 訪問的格式
1圖片 URL + 間隔標(biāo)識符 + 參數(shù)或縮略圖版本
例如:
圖片 URL 是 http://fss-my.vhostgo.com/westtest/example/demo.jpg, 間隔標(biāo)識符是 !
, 功能是 格式轉(zhuǎn)換成 webp, 訪問的 URL 是 http://fss-my.vhostgo.com/westtest/example/demo.jpg!/format/webp。
用于分隔圖片 URL 和處理信息,有 3 種可選,分別是:!
(感嘆號/默認(rèn)值)、-
(中劃線)和 _
(下劃線),可在控制中心,在 「對象存儲」 > 「bucket詳情」 中設(shè)置。
縮略圖版本可在控制中心,「對象存儲」 > 「bucket詳情」 中創(chuàng)建。
例如 縮略圖版本名稱是 west123
, 訪問的 URL 是
http://fss-my.vhostgo.com/westtest/example/demo.jpg!west123。 其中,! 是間隔標(biāo)識符。
圖片添加保護密鑰后,訪問時需要帶上 「間隔標(biāo)識符」 和 「保護密鑰」,才能訪問圖片。
例如,保護密鑰是 test
,訪問圖片 URL 是 http://fss-my.vhostgo.com/westtest/example/secret.jpg!test。 如果保護密鑰跟縮略圖版本名稱相同,當(dāng)作保護密鑰。特別地,對有保護密鑰的圖片進行處理時,不需要加保護密鑰。
假設(shè)存在縮略圖版本 west123
,現(xiàn)在針對某類圖片需要調(diào)整縮略圖版本的配置,比如限定寬度為 500px(/fw/500),可以使用縮略圖版本與參數(shù)混合,通過參數(shù)對縮略圖版本進行動態(tài)調(diào)整。因為,參數(shù)的優(yōu)先級高于縮略圖版本。 混合使用是:
xxxxxxxxxx
11http://fss-my.vhostgo.com/westtest/example/secret.jpg!west123/fw/500
上傳預(yù)處理混合使用是:
xxxxxxxxxx
11x-gmkerl-thumb: west123/fw/500
在上傳圖片時,對上傳的圖片進行處理,并保存處理后的圖片到fss。
支持的 API: REST API
參數(shù)名是 x-gmkerl-thumb
,參數(shù)值是 參數(shù)或縮略圖版本。處理參數(shù)見功能版塊。
異步處理
xxxxxxxxxx
11x-west-async: true
舉例
例 1:轉(zhuǎn)換圖片格式為 png
xxxxxxxxxx
11x-gmkerl-thumb: /format/png
例 2:限定圖片寬度為 300px、銳化、壓縮質(zhì)量 80、存儲為 png 格式(參數(shù)不區(qū)分先后順序)
xxxxxxxxxx
11x-gmkerl-thumb: /fw/300/unsharp/true/quality/80/format/png
參數(shù) | 值 | 說明 |
---|---|---|
/fw/<width> | 寬,如 300 | 限定寬度,高度自適應(yīng) |
/fh/<height> | 高,如 200 | 限定高度,寬度自適應(yīng) |
/max/<max> | 最長邊,如 200 | 限定最長邊,短邊自適應(yīng) |
/min/<min> | 最短邊,如 200 | 限定最短邊,長邊自適應(yīng) |
/fwfh/<w>x<h> | 寬x高,如 300×200 | 限定寬度或高度,寬高不足時不縮放 |
/fwfh2/<w>x<h> | 寬x高,如 300×200 | 限定寬度最小值和高度最小值,寬高不足時不縮放 |
/both/<w>x<h> | 寬x高,如 300×200 | 固定寬度和高度,寬高不足時居中裁剪再縮放。特別地,配合 /force/true 使用時,寬高不足時只縮放,不裁剪 |
/sq/<w> | 寬或高,如 300 | 圖片縮放成正方形,寬高相等 |
/scale/<scale> | 縮放比例,如 50 | 寬高等比例縮放,取值范圍 [1-1000] |
/wscale/<wscale> | 寬度縮放比例,如 200 | 寬度按比例縮放,高度不變,取值范圍 [1-1000] |
/hscale/<hscale> | 高度縮放比例,如 200 | 高度按比例縮放,寬度不變,取值范圍 [1-1000] |
/fxfn/<max>x<min> | 長邊x短邊,如 300×200 | 限定長邊或短邊,進行等比縮放,不裁剪 |
/fxfn2/<max>x<min> | 長邊x短邊,如 300×200 | 限定長邊最小值和短邊最小值,進行等比縮放,不裁剪 |
/fp/<integer> | 寬高像素積,如 200000 | 寬高等比例縮放,直到寬高像素積小于但最接近指定值,取值范圍 [1-25000000] |
/force/<boolean> | true | 不支持放大的參數(shù),指定 /force/ 為 true 進行放大,默認(rèn) false |
注
fwfh
當(dāng)原圖寬與期望縮放的寬的比例大于原圖高與期望縮放的高的比例時,是 fw
;否則,是 fh
。scale
值取20
時,縮小后的圖片寬高是原圖寬高的20%
;取200
時,放大后的圖片寬高是原圖寬高的 200%
。
/force/true
。 – <w>x<h>
中的x
是小寫字母 x
,不是乘號。
參數(shù) | 值 | 說明 |
---|---|---|
/crop/<w>x<h>a<x>a<y> | 寬x高axay,如 300x200a80a60 | 縮小或放大前進行裁剪 |
/clip/<w>x<h>a<x>a<y> | 寬x高axay,如 300x200a80a60 | 縮小或放大后進行裁剪 |
/gravity/<gravity> | 位置,如 north | 裁剪開始的方位,默認(rèn) northwest,詳見方位說明。特別地,/gravity 需要放在 /crop 或 /clip 的后面 |
/roundrect/<roundrect> | 圓角半徑,如 20 | 裁剪時對四角進行圓化(圓角裁剪),默認(rèn) 10 |
注
<w>x<h>
中的 x
是小寫字母 x
,不是乘號。當(dāng) <w>x<h>
是 0x0
時,自動根據(jù)偏移量計算裁剪圖片寬、高。
a<x>s<y>
中的 <x>
、<y>
表示偏移量,a
、s
表示正、負(fù),x
正負(fù)判斷依據(jù)是:往 east
方向偏移,為 a
;往 west
方向偏移,為 s
; y
正負(fù)判斷依據(jù)是:往 south
方向偏移,為 a
;往 north
方向偏移,為 s
。
圖片水印
參數(shù) | 值 | 說明 |
---|---|---|
/watermark/url/<url> | Base64 編碼字符串 | 水印相對路徑的 Base64 編碼,相對路徑包含 /,比如 /path/to/watermark.png。水印需要上傳到待處理圖片的服務(wù)下。詳見[注] |
/align/<align> | 位置,如 north | 水印圖片放置方位,默認(rèn) northwest,詳見方位說明 |
/margin/<x>x<y> | 橫偏移x縱偏移,如 15×10 | 水印圖片橫縱相對偏移,默認(rèn) 0x0 |
/opacity/<opacity> | 透明度,如 90 | 水印圖片透明度,默認(rèn) 100,取值范圍 [0-100],值越大越不透明,0 完全透明,100 完全不透明 |
/percent/<integer> | 百分比值,如 50 | 水印圖片自適應(yīng)原圖短邊的比例,默認(rèn) 0,表示不設(shè)置該參數(shù),詳見[注] |
/repeat/<boolean> | true | 水印圖片是否重復(fù)鋪滿原圖,默認(rèn) false |
/animate/<boolean> | true | 允許對動態(tài)圖片加水印,默認(rèn) false |
文字水印
參數(shù) | 值 | 說明 |
---|---|---|
/watermark/text/<text> | 文字內(nèi)容,如 5L2g5aW977yB | 文字內(nèi)容的 Base64 編碼字符串,示例為 你好! |
/size/<size> | 大小,如 16 | 文字大小,單位 px,默認(rèn) 40 |
/font/<font> | 字體,如 simsun(宋體) | 文字字體,默認(rèn) simsun。字體使用時,需要用參數(shù)名。參數(shù)名見字體列表 |
/color/<color> | RRGGBB,如 FF0000(紅色) | 字體顏色,默認(rèn) 000000(黑色) |
/border/<border> | RRGGBBAA,如 FF000000(不透明紅色) | 文字描邊,默認(rèn) FFFFFFFF(透明白色),詳見 border 說明 |
/align/<align> | 位置,如 north | 文字放置方位,默認(rèn) northwest,詳見方位說明 |
/margin/<x>x<y> | 橫偏移x縱偏移,如 15×10 | 文字橫縱相對偏移,默認(rèn) 0x0 |
/opacity/<opacity> | 透明度,如 90 | 文字透明度,默認(rèn) 100,取值范圍 [0-100],值越大越不透明,0 完全透明,100 完全不透明 |
/animate/<boolean> | true | 允許對動態(tài)圖片加水印,默認(rèn) false |
多個水印
xxxxxxxxxx
11/watermark/text/5L2g5aW977yB/font/simhei/watermark/url/L2RvY3MvY2xvdWQvdXB5dW4tbG9nby5wbmc=/align/southeast
特別地,水印個數(shù)越多,處理耗時越長,建議不要超過 3 個。
注
url
需要 base64 編碼,編碼后的字符串中如果包含 /
(斜杠),需要替換成 |
(豎線)。align
或 gravity
的 9 個方位:percent
取值范圍 [0-100]。當(dāng)水印沒有出現(xiàn)時,可以嘗試設(shè)置 /margin/0x0
。text
需要 base64 編碼,并把編碼后的字符串中的 /
(斜杠)替換成 |
(豎線)。text
)時,字體(font
)請使用中文字體,否則會亂碼。名稱 | 類型 | 參數(shù)名 |
---|---|---|
宋體 | 中文字體 | simsun |
黑體 | 中文字體 | simhei |
楷體 | 中文字體 | simkai |
隸書 | 中文字體 | simli |
幼圓 | 中文字體 | simyou |
仿宋 | 中文字體 | simfang |
簡體中文 | 中文字體 | sc |
繁體中文 | 中文字體 | tc |
Arial | 英文字體 | arial |
Georgia | 英文字體 | georgia |
Helvetica | 英文字體 | helvetica |
Times-New-Roman | 英文字體 | roman |
borde
r 的值 RRGGBBAA
,RRGGBB
表示邊框顏色;AA
表示不透明度,取值 [0-255],值越大越透明,00
表示完全不透明,FF
表示完全透明。
<x>x<y>
中,連接 <x>與<y>
是小寫字母 x
,不是乘號。參數(shù) | 值 | 說明 |
---|---|---|
/rotate/<固定值> | auto | 自動扶正 |
/rotate/<angle> | (0, 360],如 90° | 按角度旋轉(zhuǎn) |
參數(shù) | 值 | 說明 |
---|---|---|
/flip/<orientation> | 方向,如 left,right | 翻轉(zhuǎn)方向,可選值:left,right、top,down |
注
為圖片添加邊框,支持設(shè)置邊框顏色。
參數(shù) | 值 | 說明 |
---|---|---|
/border/<w>x<h> | 寬x高,如 3×2 | 邊框尺寸,w 表示左右邊框?qū)挾龋?/span>h 表示上下邊框?qū)挾?/span> |
/brdcolor/<brdcolor> | RRGGBBAA,如 FF000000(紅色不透明) | 邊框顏色和透明度,默認(rèn) FFFFFF00(白色不透明) |
注
RRGGBBAA
,RRGGBB
表示邊框顏色;AA
表示不透明度,取值 [0-255],值越大越透明,00
表示完全不透明,FF
表示完全透明。
<w>x<h>
中的 x
是小寫字母 x
,不是乘號。為圖片添加畫布,相當(dāng)于把圖片放入畫布中。
參數(shù) | 值 | 說明 |
---|---|---|
/canvas/<w>x<h>a<x>a<y> | 寬x高axay,如 600x400a50a20 | 畫布尺寸,w 表示畫布寬,h 表示畫布高,x、y 表示圖片左上角在畫布中的坐標(biāo),如果 x、y 不存在,則圖片在畫布中間 |
/cvscolor/<FFFFFF00> | RRGGBBAA,如 FF000000(紅色不透明) | 邊框顏色和透明度,默認(rèn) FFFFFF00(白色不透明) |
/gravity/<northwest> | 方位,如 north | 裁剪開始的方位,默認(rèn) northwest。特別地,/gravity 需要放在 /canvas 后面 |
注
cvscolor
的值 RRGGBBAA
,RRGGBB
表示邊框顏色;AA
表示不透明度,取值 [0-255],值越大越透明,00
表示完全不透明,FF
表示完全透明。
<w>x<h>
中的 x
是小寫字母 x
,不是乘號。把圖片轉(zhuǎn)換成灰白圖,適用于公祭、藝術(shù)欣賞等場景,參數(shù)如下:
參數(shù) | 值 | 說明 |
---|---|---|
/gray/<boolean> | true | 是否把圖片轉(zhuǎn)換成灰白圖,默認(rèn) false |
注
jpg
圖片,其他格式圖片可以先進行格式轉(zhuǎn)換,加 /format/jpg
。以 /exifset/
開頭,后面的參數(shù)如下:
參數(shù) | 值 | 說明 |
---|---|---|
/copyright/、<Base64 版權(quán)信息> | string | 指定 Exif 中的版權(quán)信息,需要 Base64 編碼 |
/artist/、<Base64 作者信息> | string | 指定 Exif 中的作者信息,需要 Base64 編碼 |
舉例
/exifset/copyright/dXB5dW4gaW5j/artist/5Y+I5ouN5LqR
。/copyright/
和 /artist/
關(guān)系版權(quán),請審慎編輯。參數(shù) | 值 | 說明 |
---|---|---|
/format/<圖片格式> | string | 可選值 jpg、png、webp。webp 包含動態(tài) WebP |
/lossless/<boolean> | true | 無損壓縮,默認(rèn) false。僅當(dāng)輸出格式是 WebP 時有效 |
/quality/<quality> | 整數(shù)值,如 75 | 設(shè)置壓縮質(zhì)量,可選范圍[1-99] |
/compress/<boolean> | true | JPG 、 PNG 大小壓縮優(yōu)化,默認(rèn) false |
/coalesce/<boolean> | false | 是否填充動態(tài) GIF 圖像中共同部分,默認(rèn) true,見「注」 |
/progressive/<boolean> | true | JPG 圖片漸進式加載,圖片加載從模糊到清晰 |
/exifswitch/<boolean> | true | 保留 EXIF 信息 ,默認(rèn)會刪除 EXIF 信息 |
/noicc/<boolean> | true | 清除圖片 ICC 信息,默認(rèn) false |
/strip/<boolean> | true | 去除圖片所有元信息,包括 EXIF 、ICC 等。默認(rèn) false |
/ignore-error/<boolean> | true | 是否忽略錯誤返回原圖 ,默認(rèn) false,返回錯誤 |
注
quality
(質(zhì)量) 是 75
,在這個值壓縮大小與圖片質(zhì)量損失得到平衡。compress
會對 JPG/PNG
進行一次壓縮以減少圖片體積,同時稍微延長了圖片處理時間、降低了圖片質(zhì)量。noicc
會導(dǎo)致圖片質(zhì)量輕微的下降。GIF
可以通過省略相鄰幀之間共同部分來優(yōu)化圖片體積。如果 coalesce
參數(shù)為 false
,當(dāng)對動態(tài) GIF
做縮略或放大時,可能會導(dǎo)致圖片質(zhì)量下降。
參數(shù) | 值 | 說明 |
---|---|---|
/excolor/<integer> | 顏色數(shù)量,如 128 | 提取的顏色數(shù)量??蛇x值:[1-4096] |
/exformat/<exformat> | 顏色進制,如 hex | 返回顏色的進制,默認(rèn) dec??蛇x值:dec、hex |
注
JSON
格式返回顏色。hex(十六進制)
表示顏色為 0xRRGGBB
,如 0xff00aa
;dec(十進制
) 表示顏色為 12345678
。
參數(shù) | 值 | 說明 |
---|---|---|
/gdori/<orientation> | 方向,如 top,down(自上而下) | 漸變方向 |
/gdpos/<gdpos> | 開始位置,結(jié)束位置,如 10,100 | 漸變從開始位置至結(jié)束位置。單位像素(px) |
/gdstartcolor/<gdstartcolor> | RRGGBBAA,如 FF000000(紅色不透明) | 開始位置顏色及透明度 |
/gdstopcolor/<gdstopcolor> | RRGGBBAA,如 FF000000(紅色不透明) | 結(jié)束位置顏色及透明度 |
注
gdori
取值:top,down
(自上而下)、bottom,up
(自下而上)、left,right
(自左向右)、right,left
(自右向左)。
RRGGBBAA
:RRGGBB
表示邊框顏色;AA
表示不透明度,取值 [0-255],值越大越透明,00
表示完全不透明,FF
表示完全透明。