圖片處理

URL 訪問

通過 URL 訪問圖片時(shí)，對(duì)圖片進(jìn)行處理，并把處理后的圖片返回。

URL 訪問的格式

1
圖片 URL + 間隔標(biāo)識(shí)符 + 參數(shù)或縮略圖版本

例如：

圖片 URL 是 http://fss-my.vhostgo.com/westtest/example/demo.jpg， 間隔標(biāo)識(shí)符是 !， 功能是 格式轉(zhuǎn)換成 webp， 訪問的 URL 是 http://fss-my.vhostgo.com/westtest/example/demo.jpg!/format/webp。

間隔標(biāo)識(shí)符

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

縮略圖版本

縮略圖版本可在控制中心，「對(duì)象存儲(chǔ)」 > 「bucket詳情」 中創(chuàng)建。

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

http://fss-my.vhostgo.com/westtest/example/demo.jpg!west123。 其中，! 是間隔標(biāo)識(shí)符。

原圖保護(hù)密鑰

• 上傳圖片時(shí)，保護(hù)密鑰通過 REST API 的 Content-Secret 設(shè)置。
• 已經(jīng)存在存儲(chǔ)的圖片，可以通過編輯 Metadata 設(shè)置保護(hù)密鑰。

圖片添加保護(hù)密鑰后，訪問時(shí)需要帶上 「間隔標(biāo)識(shí)符」 和 「保護(hù)密鑰」，才能訪問圖片。

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

混合使用

假設(shè)存在縮略圖版本 west123，現(xiàn)在針對(duì)某類圖片需要調(diào)整縮略圖版本的配置，比如限定寬度為 500px（/fw/500），可以使用縮略圖版本與參數(shù)混合，通過參數(shù)對(duì)縮略圖版本進(jìn)行動(dòng)態(tài)調(diào)整。因?yàn)?，參?shù)的優(yōu)先級(jí)高于縮略圖版本。 混合使用是：

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

上傳預(yù)處理混合使用是：

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

上傳預(yù)處理

在上傳圖片時(shí)，對(duì)上傳的圖片進(jìn)行處理，并保存處理后的圖片到fss。

支持的 API： REST API

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

異步處理

xxxxxxxxxx
1
1
x-west-async: true

舉例

例 1：轉(zhuǎn)換圖片格式為 png

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

例 2：限定圖片寬度為 300px、銳化、壓縮質(zhì)量 80、存儲(chǔ)為 png 格式（參數(shù)不區(qū)分先后順序）

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

縮小&放大

參數(shù)	值	說明
/fw/<width>	寬，如 300	限定寬度，高度自適應(yīng)
/fh/<height>	高，如 200	限定高度，寬度自適應(yīng)
/max/<max>	最長(zhǎng)邊，如 200	限定最長(zhǎng)邊，短邊自適應(yīng)
/min/<min>	最短邊，如 200	限定最短邊，長(zhǎng)邊自適應(yīng)
/fwfh/<w>x<h>	寬x高，如 300×200	限定寬度或高度，寬高不足時(shí)不縮放
/fwfh2/<w>x<h>	寬x高，如 300×200	限定寬度最小值和高度最小值，寬高不足時(shí)不縮放
/both/<w>x<h>	寬x高，如 300×200	固定寬度和高度，寬高不足時(shí)居中裁剪再縮放。特別地，配合 /force/true 使用時(shí)，寬高不足時(shí)只縮放，不裁剪
/sq/<w>	寬或高，如 300	圖片縮放成正方形，寬高相等
/scale/<scale>	縮放比例，如 50	寬高等比例縮放，取值范圍 [1-1000]
/wscale/<wscale>	寬度縮放比例，如 200	寬度按比例縮放，高度不變，取值范圍 [1-1000]
/hscale/<hscale>	高度縮放比例，如 200	高度按比例縮放，寬度不變，取值范圍 [1-1000]
/fxfn/<max>x<min>	長(zhǎng)邊x短邊，如 300×200	限定長(zhǎng)邊或短邊，進(jìn)行等比縮放，不裁剪
/fxfn2/<max>x<min>	長(zhǎng)邊x短邊，如 300×200	限定長(zhǎng)邊最小值和短邊最小值，進(jìn)行等比縮放，不裁剪
/fp/<integer>	寬高像素積，如 200000	寬高等比例縮放，直到寬高像素積小于但最接近指定值，取值范圍 [1-25000000]
/force/<boolean>	true	不支持放大的參數(shù)，指定 /force/ 為 true 進(jìn)行放大，默認(rèn) false

注

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

裁剪

參數(shù)	值	說明
/crop/<w>x<h>a<x>a<y>	寬x高axay，如 300x200a80a60	縮小或放大前進(jìn)行裁剪
/clip/<w>x<h>a<x>a<y>	寬x高axay，如 300x200a80a60	縮小或放大后進(jìn)行裁剪
/gravity/<gravity>	位置，如 north	裁剪開始的方位，默認(rèn) northwest，詳見方位說明。特別地，/gravity 需要放在 /crop 或 /clip 的后面
/roundrect/<roundrect>	圓角半徑，如 20	裁剪時(shí)對(duì)四角進(jìn)行圓化（圓角裁剪），默認(rèn) 10

注

• <w>x<h> 中的 x 是小寫字母 x，不是乘號(hào)。當(dāng) <w>x<h> 是 0x0 時(shí)，自動(dòng)根據(jù)偏移量計(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 編碼字符串	水印相對(duì)路徑的 Base64 編碼，相對(duì)路徑包含 /，比如 /path/to/watermark.png。水印需要上傳到待處理圖片的服務(wù)下。詳見[注]
/align/<align>	位置，如 north	水印圖片放置方位，默認(rèn) northwest，詳見方位說明
/margin/<x>x<y>	橫偏移x縱偏移，如 15×10	水印圖片橫縱相對(duì)偏移，默認(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	允許對(duì)動(dòng)態(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ù)名。參數(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	文字橫縱相對(duì)偏移，默認(rèn) 0x0
/opacity/<opacity>	透明度，如 90	文字透明度，默認(rèn) 100，取值范圍 [0-100]，值越大越不透明，0 完全透明，100 完全不透明
/animate/<boolean>	true	允許對(duì)動(dòng)態(tài)圖片加水印，默認(rèn) false

多個(gè)水印

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

特別地，水印個(gè)數(shù)越多，處理耗時(shí)越長(zhǎng)，建議不要超過 3 個(gè)。

注

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

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

名稱	類型	參數(shù)名
宋體	中文字體	simsun
黑體	中文字體	simhei
楷體	中文字體	simkai
隸書	中文字體	simli
幼圓	中文字體	simyou
仿宋	中文字體	simfang
簡(jiǎn)體中文	中文字體	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，不是乘號(hào)。

旋轉(zhuǎn)

參數(shù)	值	說明
/rotate/<固定值>	auto	自動(dòng)扶正
/rotate/<angle>	(0, 360]，如 90°	按角度旋轉(zhuǎn)

翻轉(zhuǎn)

參數(shù)	值	說明
/flip/<orientation>	方向，如 left,right	翻轉(zhuǎn)方向，可選值：left,right、top,down

注

• left,right 表示從左向右翻轉(zhuǎn)，top,down 表示從上向下翻轉(zhuǎn)。

邊框

為圖片添加邊框，支持設(shè)置邊框顏色。

參數(shù)	值	說明
/border/<w>x<h>	寬x高，如 3×2	邊框尺寸，w 表示左右邊框?qū)挾龋?/span>h 表示上下邊框?qū)挾?/span>
/brdcolor/<brdcolor>	RRGGBBAA，如 FF000000（紅色不透明）	邊框顏色和透明度，默認(rèn) FFFFFF00（白色不透明）

注

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

畫布

為圖片添加畫布，相當(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，不是乘號(hào)。

灰白圖

把圖片轉(zhuǎn)換成灰白圖，適用于公祭、藝術(shù)欣賞等場(chǎng)景，參數(shù)如下：

參數(shù)	值	說明
/gray/<boolean>	true	是否把圖片轉(zhuǎn)換成灰白圖，默認(rèn) false

注

• 暫時(shí)只支持 jpg 圖片，其他格式圖片可以先進(jìn)行格式轉(zhuǎn)換，加 /format/jpg。

Exif 編輯

以 /exifset/ 開頭，后面的參數(shù)如下：

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

舉例

• 同時(shí)修改版權(quán)和作者信息：/exifset/copyright/dXB5dW4gaW5j/artist/5Y+I5ouN5LqR。
• /copyright/ 和 /artist/ 關(guān)系版權(quán)，請(qǐng)審慎編輯。

輸出設(shè)置

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

注

• 一般來說，quality（質(zhì)量） 是 75，在這個(gè)值壓縮大小與圖片質(zhì)量損失得到平衡。
• compress 會(huì)對(duì) JPG/PNG 進(jìn)行一次壓縮以減少圖片體積，同時(shí)稍微延長(zhǎng)了圖片處理時(shí)間、降低了圖片質(zhì)量。
• noicc 會(huì)導(dǎo)致圖片質(zhì)量輕微的下降。
• 大部分動(dòng)態(tài) GIF 可以通過省略相鄰幀之間共同部分來優(yōu)化圖片體積。如果 coalesce 參數(shù)為 false，當(dāng)對(duì)動(dòng)態(tài) GIF 做縮略或放大時(shí)，可能會(huì)導(dǎo)致圖片質(zhì)量下降。

主題色提取

參數(shù)	值	說明
/excolor/<integer>	顏色數(shù)量，如 128	提取的顏色數(shù)量。可選值：[1-4096]
/exformat/<exformat>	顏色進(jìn)制，如 hex	返回顏色的進(jìn)制，默認(rèn) dec?？蛇x值：dec、hex

注

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

靜態(tài)圖漸變

參數(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 表示完全透明。