圖片處理

URL 訪問

通過 URL 訪問圖片時，對圖片進行處理，并把處理后的圖片返回。

URL 訪問的格式

1
圖片 URL + 間隔標識符 + 參數或縮略圖版本

例如：

圖片 URL 是 http://fss-my.vhostgo.com/westtest/example/demo.jpg， 間隔標識符是 !， 功能是 格式轉換成 webp， 訪問的 URL 是 http://fss-my.vhostgo.com/westtest/example/demo.jpg!/format/webp。

間隔標識符

用于分隔圖片 URL 和處理信息，有 3 種可選，分別是：!（感嘆號/默認值）、-（中劃線）和 _（下劃線），可在控制中心，在 「對象存儲」 > 「bucket詳情」 中設置。

縮略圖版本

縮略圖版本可在控制中心，「對象存儲」 > 「bucket詳情」 中創建。

例如 縮略圖版本名稱是 west123， 訪問的 URL 是

http://fss-my.vhostgo.com/westtest/example/demo.jpg!west123。 其中，! 是間隔標識符。

原圖保護密鑰

• 上傳圖片時，保護密鑰通過 REST API 的 Content-Secret 設置。
• 已經存在存儲的圖片，可以通過編輯 Metadata 設置保護密鑰。

圖片添加保護密鑰后，訪問時需要帶上 「間隔標識符」 和 「保護密鑰」，才能訪問圖片。

例如，保護密鑰是 test，訪問圖片 URL 是 http://fss-my.vhostgo.com/westtest/example/secret.jpg!test。 如果保護密鑰跟縮略圖版本名稱相同，當作保護密鑰。特別地，對有保護密鑰的圖片進行處理時，不需要加保護密鑰。

混合使用

假設存在縮略圖版本 west123，現在針對某類圖片需要調整縮略圖版本的配置，比如限定寬度為 500px（/fw/500），可以使用縮略圖版本與參數混合，通過參數對縮略圖版本進行動態調整。因為，參數的優先級高于縮略圖版本。 混合使用是：

xxxxxxxxxx
1
1
http://fss-my.vhostgo.com/westtest/example/secret.jpg!west123/fw/500

上傳預處理混合使用是：

xxxxxxxxxx
1
1
x-gmkerl-thumb: west123/fw/500

上傳預處理

在上傳圖片時，對上傳的圖片進行處理，并保存處理后的圖片到fss。

支持的 API： REST API

參數名是 x-gmkerl-thumb，參數值是 參數或縮略圖版本。處理參數見功能版塊。

異步處理

xxxxxxxxxx
1
1
x-west-async: true

舉例

例 1：轉換圖片格式為 png

xxxxxxxxxx
1
1
x-gmkerl-thumb: /format/png

例 2：限定圖片寬度為 300px、銳化、壓縮質量 80、存儲為 png 格式（參數不區分先后順序）

xxxxxxxxxx
1
1
x-gmkerl-thumb: /fw/300/unsharp/true/quality/80/format/png

縮小&放大

參數	值	說明
/fw/<width>	寬，如 300	限定寬度，高度自適應
/fh/<height>	高，如 200	限定高度，寬度自適應
/max/<max>	最長邊，如 200	限定最長邊，短邊自適應
/min/<min>	最短邊，如 200	限定最短邊，長邊自適應
/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	不支持放大的參數，指定 /force/ 為 true 進行放大，默認 false

注

• fwfh 當原圖寬與期望縮放的寬的比例大于原圖高與期望縮放的高的比例時，是 fw；否則，是 fh。
• scale 值取20時，縮小后的圖片寬高是原圖寬高的20%；取200 時，放大后的圖片寬高是原圖寬高的 200%。
• 特別地，大部分參數默認不支持放大，如果需要放大，請指定 /force/true 。 – <w>x<h> 中的x是小寫字母 x，不是乘號。

裁剪

參數	值	說明
/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	裁剪開始的方位，默認 northwest，詳見方位說明。特別地，/gravity 需要放在 /crop 或 /clip 的后面
/roundrect/<roundrect>	圓角半徑，如 20	裁剪時對四角進行圓化（圓角裁剪），默認 10

注

• <w>x<h> 中的 x 是小寫字母 x，不是乘號。當 <w>x<h> 是 0x0 時，自動根據偏移量計算裁剪圖片寬、高。
• a<x>s<y> 中的 <x>、<y> 表示偏移量，a、s 表示正、負，x 正負判斷依據是：往 east 方向偏移，為 a；往 west 方向偏移，為 s; y 正負判斷依據是：往 south 方向偏移，為 a；往 north 方向偏移，為 s。

水印

圖片水印

參數	值	說明
/watermark/url/<url>	Base64 編碼字符串	水印相對路徑的 Base64 編碼，相對路徑包含 /，比如 /path/to/watermark.png。水印需要上傳到待處理圖片的服務下。詳見[注]
/align/<align>	位置，如 north	水印圖片放置方位，默認 northwest，詳見方位說明
/margin/<x>x<y>	橫偏移x縱偏移，如 15×10	水印圖片橫縱相對偏移，默認 0x0
/opacity/<opacity>	透明度，如 90	水印圖片透明度，默認 100，取值范圍 [0-100]，值越大越不透明，0 完全透明，100 完全不透明
/percent/<integer>	百分比值，如 50	水印圖片自適應原圖短邊的比例，默認 0，表示不設置該參數，詳見[注]
/repeat/<boolean>	true	水印圖片是否重復鋪滿原圖，默認 false
/animate/<boolean>	true	允許對動態圖片加水印，默認 false

文字水印

參數	值	說明
/watermark/text/<text>	文字內容，如 5L2g5aW977yB	文字內容的 Base64 編碼字符串，示例為 你好！
/size/<size>	大小，如 16	文字大小，單位 px，默認 40
/font/<font>	字體，如 simsun（宋體）	文字字體，默認 simsun。字體使用時，需要用參數名。參數名見字體列表
/color/<color>	RRGGBB，如 FF0000（紅色）	字體顏色，默認 000000（黑色）
/border/<border>	RRGGBBAA，如 FF000000（不透明紅色）	文字描邊，默認 FFFFFFFF（透明白色），詳見 border 說明
/align/<align>	位置，如 north	文字放置方位，默認 northwest，詳見方位說明
/margin/<x>x<y>	橫偏移x縱偏移，如 15×10	文字橫縱相對偏移，默認 0x0
/opacity/<opacity>	透明度，如 90	文字透明度，默認 100，取值范圍 [0-100]，值越大越不透明，0 完全透明，100 完全不透明
/animate/<boolean>	true	允許對動態圖片加水印，默認 false

多個水印

xxxxxxxxxx
1
1
/watermark/text/5L2g5aW977yB/font/simhei/watermark/url/L2RvY3MvY2xvdWQvdXB5dW4tbG9nby5wbmc=/align/southeast

特別地，水印個數越多，處理耗時越長，建議不要超過 3 個。

注

• 水印需要上傳到待處理圖片的服務下，水印 URL 使用的是相對路徑，不包含 Domain（域名）。
• 水印的 url 需要 base64 編碼，編碼后的字符串中如果包含 /（斜杠），需要替換成 |（豎線）。
• align 或 gravity 的 9 個方位：

• 圖片水印的 percent 取值范圍 [0-100]。當水印沒有出現時，可以嘗試設置 /margin/0x0。
• 文字水印的 text 需要 base64 編碼，并把編碼后的字符串中的 /（斜杠）替換成 |（豎線）。
• 文字水印的中含中文內容（text）時，字體（font）請使用中文字體，否則會亂碼。

名稱	類型	參數名
宋體	中文字體	simsun
黑體	中文字體	simhei
楷體	中文字體	simkai
隸書	中文字體	simli
幼圓	中文字體	simyou
仿宋	中文字體	simfang
簡體中文	中文字體	sc
繁體中文	中文字體	tc
Arial	英文字體	arial
Georgia	英文字體	georgia
Helvetica	英文字體	helvetica
Times-New-Roman	英文字體	roman

• border 的值 RRGGBBAA，RRGGBB 表示邊框顏色；AA 表示不透明度，取值 [0-255]，值越大越透明，00 表示完全不透明，FF 表示完全透明。
• <x>x<y> 中，連接 <x>與<y>是小寫字母 x，不是乘號。

旋轉

參數	值	說明
/rotate/<固定值>	auto	自動扶正
/rotate/<angle>	(0, 360]，如 90°	按角度旋轉

翻轉

參數	值	說明
/flip/<orientation>	方向，如 left,right	翻轉方向，可選值：left,right、top,down

注

• left,right 表示從左向右翻轉，top,down 表示從上向下翻轉。

邊框

為圖片添加邊框，支持設置邊框顏色。

參數	值	說明
/border/<w>x<h>	寬x高，如 3×2	邊框尺寸，w 表示左右邊框寬度，h 表示上下邊框寬度
/brdcolor/<brdcolor>	RRGGBBAA，如 FF000000（紅色不透明）	邊框顏色和透明度，默認 FFFFFF00（白色不透明）

注

• brdcolor 的值 RRGGBBAA，RRGGBB 表示邊框顏色；AA 表示不透明度，取值 [0-255]，值越大越透明，00 表示完全不透明，FF 表示完全透明。
• <w>x<h> 中的 x 是小寫字母 x，不是乘號。

畫布

為圖片添加畫布，相當于把圖片放入畫布中。

參數	值	說明
/canvas/<w>x<h>a<x>a<y>	寬x高axay，如 600x400a50a20	畫布尺寸，w 表示畫布寬，h 表示畫布高，x、y 表示圖片左上角在畫布中的坐標，如果 x、y 不存在，則圖片在畫布中間
/cvscolor/<FFFFFF00>	RRGGBBAA，如 FF000000（紅色不透明）	邊框顏色和透明度，默認 FFFFFF00（白色不透明）
/gravity/<northwest>	方位，如 north	裁剪開始的方位，默認 northwest。特別地，/gravity 需要放在 /canvas 后面

注

• cvscolor 的值 RRGGBBAA，RRGGBB 表示邊框顏色；AA 表示不透明度，取值 [0-255]，值越大越透明，00 表示完全不透明，FF 表示完全透明。
• <w>x<h> 中的 x 是小寫字母 x，不是乘號。

灰白圖

把圖片轉換成灰白圖，適用于公祭、藝術欣賞等場景，參數如下：

參數	值	說明
/gray/<boolean>	true	是否把圖片轉換成灰白圖，默認 false

注

• 暫時只支持 jpg 圖片，其他格式圖片可以先進行格式轉換，加 /format/jpg。

Exif 編輯

以 /exifset/ 開頭，后面的參數如下：

參數	值	說明
/copyright/、<Base64 版權信息>	string	指定 Exif 中的版權信息，需要 Base64 編碼
/artist/、<Base64 作者信息>	string	指定 Exif 中的作者信息，需要 Base64 編碼

舉例

• 同時修改版權和作者信息：/exifset/copyright/dXB5dW4gaW5j/artist/5Y+I5ouN5LqR。
• /copyright/ 和 /artist/ 關系版權，請審慎編輯。

輸出設置

參數	值	說明
/format/<圖片格式>	string	可選值 jpg、png、webp。webp 包含動態 WebP
/lossless/<boolean>	true	無損壓縮，默認 false。僅當輸出格式是 WebP 時有效
/quality/<quality>	整數值，如 75	設置壓縮質量，可選范圍[1-99]
/compress/<boolean>	true	JPG 、 PNG 大小壓縮優化，默認 false
/coalesce/<boolean>	false	是否填充動態 GIF 圖像中共同部分，默認 true，見「注」
/progressive/<boolean>	true	JPG 圖片漸進式加載，圖片加載從模糊到清晰
/exifswitch/<boolean>	true	保留 EXIF 信息 ，默認會刪除 EXIF 信息
/noicc/<boolean>	true	清除圖片 ICC 信息，默認 false
/strip/<boolean>	true	去除圖片所有元信息，包括 EXIF 、ICC 等。默認 false
/ignore-error/<boolean>	true	是否忽略錯誤返回原圖 ，默認 false，返回錯誤

注

• 一般來說，quality（質量） 是 75，在這個值壓縮大小與圖片質量損失得到平衡。
• compress 會對 JPG/PNG 進行一次壓縮以減少圖片體積，同時稍微延長了圖片處理時間、降低了圖片質量。
• noicc 會導致圖片質量輕微的下降。
• 大部分動態 GIF 可以通過省略相鄰幀之間共同部分來優化圖片體積。如果 coalesce 參數為 false，當對動態 GIF 做縮略或放大時，可能會導致圖片質量下降。

主題色提取

參數	值	說明
/excolor/<integer>	顏色數量，如 128	提取的顏色數量。可選值：[1-4096]
/exformat/<exformat>	顏色進制，如 hex	返回顏色的進制，默認 dec。可選值：dec、hex

注

• 以 JSON 格式返回顏色。hex（十六進制） 表示顏色為 0xRRGGBB，如 0xff00aa；dec（十進制） 表示顏色為 12345678。

靜態圖漸變

參數	值	說明
/gdori/<orientation>	方向，如 top,down（自上而下）	漸變方向
/gdpos/<gdpos>	開始位置,結束位置，如 10,100	漸變從開始位置至結束位置。單位像素（px）
/gdstartcolor/<gdstartcolor>	RRGGBBAA，如 FF000000（紅色不透明）	開始位置顏色及透明度
/gdstopcolor/<gdstopcolor>	RRGGBBAA，如 FF000000（紅色不透明）	結束位置顏色及透明度

注

• gdori 取值：top,down（自上而下）、bottom,up（自下而上）、left,right（自左向右）、right,left（自右向左）。
• RRGGBBAA：RRGGBB 表示邊框顏色；AA 表示不透明度，取值 [0-255]，值越大越透明，00 表示完全不透明，FF 表示完全透明。