Documentation

KuronekoServer CDN API

画像変換、CSS・JavaScript最適化、Package Libraryの利用方法をまとめています。認証は不要です。

利用を始める OpenAPI JSON →

クイックスタート

CDN上にある元ファイルのURLへクエリパラメータを追加します。変換後のファイルがそのままレスポンスとして返ります。

GET /images/photo.jpg?width=800&format=webp&quality=85 
curl -o photo.webp \
  'https://cdn.krnk.org/images/photo.jpg?width=800&format=webp&quality=85'

API形式で呼び出す場合は、元ファイルをfileへ指定します。

GET /?file=images/photo.jpg&width=800&format=webp
fileにはドキュメントルートからの相対パスを指定します。絶対パス、..、キャッシュディレクトリは指定できません。

画像最適化

JPEG、PNG / APNG、GIF、WebP、AVIF、BMP、TIFF、TGA、PBM、HEIC / HEIFを入力として扱います。利用可能な形式はサーバーの画像コーデックにも依存します。

変換は、切り抜き、リサイズ、反転・回転、ぼかし・シャープ、色調整、出力形式・品質の順に適用されます。

サイズ・切り抜き

パラメータ 値 説明
width / w 1–50000 最大幅。縦横比を維持します。
height / h 1–50000 最大高さ。縦横比を維持します。
upscaling off / resampling 元画像を超える拡大を許可します。既定はoffです。
crop w,h / w,h,x,y 基準位置または座標を使って切り抜きます。
aspect_ratio 16:9など 中央基準で指定比率へ切り抜きます。
crop_gravity center、northなど 2値形式のcropで基準位置を指定します。
focus_crop w,h,x,y x/yにはピクセル座標または0.0–1.0の相対座標を指定します。 
/images/photo.jpg?crop=1200,630&width=600
/images/photo.jpg?aspect_ratio=1:1&width=512
/images/photo.jpg?focus_crop=800,600,0.4,0.35
Face Detectionは行いません。face_cropを指定したリクエストはHTTP 400になります。

回転・色調整

パラメータ 値 説明
flip / flop boolean 上下反転 / 左右反転。
rotate -270、-180、-90、0、90、180、270 時計回りの回転角度。
blur 0–100 ぼかしの強度。
sharpen true / 0–100 自動または指定強度でシャープ化します。
brightness -100–100 負数で暗く、正数で明るくします。
gamma -100–100 中間調を補正します。
contrast -100–100 コントラストを調整します。
saturation -100–100 彩度を調整します。
hue 0–100 色相を回転します。
tint 6桁の16進カラー #を付けずに指定します。
sepia 0–100 セピア効果の強度。 
/images/photo.jpg?brightness=10&contrast=8&saturation=15
/images/photo.jpg?rotate=90&flop=true&sharpen=25

出力形式・品質

パラメータ 値 説明
format / f jpeg、png、gif、webp、avif 出力形式。省略時は入力形式またはAcceptヘッダーを使用します。
quality / q 0–100 JPEG、WebP、AVIFの品質。既定値は85です。

formatを省略し、リクエストのAcceptがimage/webpを含む場合はWebPを優先します。

CSS・JavaScript最適化

CSSとJavaScriptは、画像と同じように元ファイルのURLへパラメータを追加して処理できます。

パラメータ 値 説明
min 0 / 1 不要な空白やコメントを除去します。
compress 0 / 1 対応クライアントへgzip圧縮で返します。
safe 0 / 1 JavaScriptで改行・末尾空白だけを整理する安全モードです。 
/assets/app.css?min=1&compress=1
/assets/app.js?min=1&safe=1&compress=1

Package Library

Package Libraryからパッケージを検索できます。検索結果は、バージョンを固定したKuronekoServer CDNのURLとして利用できます。

GET /npm/search?q=three&limit=12

パッケージ

パッケージ直下のURLは、パッケージに定義された既定エントリーファイルを解決します。必要に応じてファイルパスも明示できます。 

/npm/three@0.185.1/
/npm/three@0.185.1/build/three.module.js
/npm/@scope/package@1.2.3/dist/index.js

ライブラリ

ライブラリURLでは、バージョンとファイルパスを指定します。

/npm/lib/jquery@3.7.1/jquery.min.js
  • 変更されない完全なバージョンを指定してください。
  • latestやバージョン範囲は使用できません。
  • 1ファイルの上限は20 MiBです。
  • HTMLファイルは配信しません。
  • 初回取得後はローカルキャッシュから再利用されます。

リクエストとレスポンス

GET、HEAD、OPTIONSを利用できます。HEADは本文を返さず、変換結果やパッケージのヘッダーだけを確認します。

条件付きリクエスト

ヘッダー 用途
If-None-Match 以前のETagと一致する場合は304を返します。
If-Modified-Since ETagがない場合に更新日時を評価します。
Accept-Encoding CSS・JavaScriptのgzip圧縮可否を伝えます。

主なレスポンスヘッダー

  • Cache-Control — クライアントと配信キャッシュの保持条件
  • ETag / Last-Modified — 条件付きリクエスト
  • X-Optimizer-Status — 画像・アセット処理結果
  • X-Package-Cache — パッケージのローカルキャッシュ状態
  • CDN-Cache — 配信キャッシュ状態

HTTPステータス

ステータス 意味
200 処理または配信に成功
304 条件付きリクエストで未変更
400 パラメータ、パス、バージョンが不正
404 元ファイルまたはパッケージが見つからない
405 許可されていないHTTPメソッド
413 入力またはパッケージが上限を超過
415 対応していない形式
500 / 501 処理エラーまたは必要なコーデックが利用不可
502 パッケージ検索・取得先へ接続できない

制限事項

  • 入力画像は最大50メガピクセルです。
  • 拡大出力は最大24メガピクセルです。
  • AVIF出力は最大4メガピクセルです。
  • WebP出力は幅・高さとも最大16,383ピクセルです。
  • 画像変換処理の上限時間は60秒です。
  • Face Detectionには対応していません。

OpenAPI

自動生成、クライアント実装、仕様検証には独立したOpenAPI JSONを使用してください。このページは人が読むためのガイドです。

OpenAPI 3.1 JSON エンドポイント、パラメータ、レスポンススキーマ
openapi.jsonを開く →