---
title: "Query String作成ガイド"
slug: "media-media-3-2"
tags: ["query string"]
updated: 2026-09-17T09:28:48Z
published: 2026-09-17T09:28:48Z
canonical: "guide.ncloud-docs.com/media-media-3-2"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query String作成ガイド

Classic/VPC環境で利用できます。

## サムネイル呼び出し URLの作成方法

- オブジェクトストレージとの連携時: CDNドメイン+オブジェクトストレージ内のファイルパス+サムネイル作成オプションの組み合わせで作成します。
  - 形式: `https://{CDN-DOMAIN}/{FILE-PATH-IN-OBJSTORAGE}?{QUERYSTRINGS}`
  - 例: `https://abc123xyz.cdn.ntruss.com/a/b.jpg?type=h_wm&h=780&quality=90&autorotate=true`

          参考

          

HTTP URLとの連携は JPリージョンでのみ利用可能で、KRリージョンは2023年4月から利用できます。

- HTTP URLとの連携時: CDNドメイン+外部 URL+サムネイル作成オプションの組み合わせで作成します。
  - 形式: `https://{CDN-DOMAIN}?src="{외부이미지URL}"&{QUERYSTRINGS}`
  - 例: `https://abc123xyz.cdn.ntruss.com?src="{외부 이미지 URL}"&type=h_wm&h=780&quality=90&autorotate=true`

Image Optimizerがサポートするサムネイル作成のオプションは Query Stringを利用して作成します。 サムネイル作成の結果は Query Stringのパラメータ(オプション)の順番に影響されません。 ただし、実行の結果、同じサムネイルを作る Query Stringでも、パラメータのデフォルト値設定の有無によって新しい変換のリクエストと認識し、変換の回数が加算される可能性があるので、ご注意ください。例えば、`/a.jpg?type=f&w=40&h=40`と`/a.jpg?type=f&w=40&h=40&quality=90`は完全に同じサムネイルを作成しますが、それぞれ課金される可能性があります。

## Query Stringの説明

Query Stringを構成するオプションは、大きく typeパラメータに従属するオプションとすべての typeに共通して適用できる全域オプションに分かれます。

### 全域オプション

- quality: 元の画像が JPEG形式の場合にのみ該当し、1~100を範囲とする整数を設定(デフォルト値: 90)
- autorotate: true/falseの文字列を設定。EXIFの回転情報をベースに結果のサムネイルを自動回転(デフォルト値: true)
- anilimit: GIF形式に複数枚のフレームが存在する場合、指定のフレーム以降は削除。前から表示されるフレームの数は1~100(デフォルト値: 1)
- ttype: サムネイルのファイル形式を設定(jpg, gif, png)、設定しない場合は元画像と同じ形式
- src
  - サムネイル作成の元となる外部の画像 URL情報を入力
  - URL内に?、&のようなデリミタが存在する場合、%22 (")で URLを囲いパーセントエンコーディングしてから入力
  - "がないと decodeされない。"で囲った URLは1回 decodeされる
  - 画像ファイルのサイズは30MBに制限され、HTTP Redirectは1回まで可能

### typeパラメータと従属オプション

#### サイズ

- リサイズとクロップ(type=f): 元画像の比率を維持しつつ画像のサイズを縮小または拡大した後、残った領域をクロップ
  - w: 横の長さ、1以上の整数、必須入力
  - h: 縦の長さ、1以上の整数、必須入力
- align: クロップして残す位置、9分割位置、0~8、デフォルト値は4(中央)
  - faceopt: 顔認識の適用有無、true/falseの文字列、デフォルト値は「false」
- リサイズ(type=m): 設定した横、縦の大きさに収まるように画像のサイズを変更
  - w: 横の長さ、1以上の整数、必須入力
  - h: 縦の長さ、1以上の整数、必須入力
  - bgcolor: 上下または両端に入れる色、存在しない場合は横と縦の値が無視される(RGBの16進数カラーコード、6文字の文字列)
  - extopt: サムネイルが元画像より小さい場合に拡大するかどうか、整数3は拡大、デフォルト値は0(元のサイズを維持)
- 横変換(type=w): 元の比率を維持しつつ横の長さを基準に画像のサイズを変更
  - w: 横の長さ、1以上の整数、必須入力
  - extopt: サムネイルが元画像より小さい場合に拡大するかどうか、整数3は拡大、デフォルト値は0(元のサイズを維持)
- 縦変換(type=h): 元の比率を維持しつつ縦の長さを基準に画像のサイズを変更
  - h: 縦の長さ、1以上の整数、必須入力
- 強制変換(type=u): 元の比率を無視して指定するサイズに強制変更
  - w: 横の長さ、1以上の整数、必須入力
  - h: 縦の長さ、1以上の整数、必須入力

#### ウォーターマーク

- ウォーターマーク(type=wm)
  - wm_path: ウォーターマークを入れる画像の URL(HTTPを含む、必須)。ウォーターマークの画像がウォーターマークを入れる画像より小さい必要がある。
  - wm_align: ウォーターマークの位置を指定する際の基準点。各9分割領域の左上の地点。0~8、デフォルト値は4。
  - wm_offx: 基準点から右方向に離れた距離。0以上の整数、デフォルト値は0。
  - wm_offy: 基準点から下方向に離れた距離。0以上の整数、デフォルト値は0。

#### フィルタ

- Sharpen(type=sh): 画像を鮮明に見せる効果
  - sharp_amt: 輪郭線に付けるコントラストの程度、必須入力
- Blur(type=bl): 画像にぼかしを入れる効果
  - blur_rad: 効果を適用するためのマスクのサイズ(ピクセル単位の半径)
  - blur_sig: ブラーマスク内で適用する分散の程度、必須入力
- Black & White(type=bw): 画像の色を白黒に変更

### 多重 typeのパラメータ

サイズ、ウォーターマーク、フィルタはデリミタである `_`を基準に最初から順番に適用されます。 例: `f_wm`(リサイズとクロップ処理の後、ウォーターマークを適用), `bw_wm`(白黒処理の後、ウォーターマークを適用)

## ユースケース

- リサイズとクロップ
  - 横100、縦100に縮小した後、残った部分はクロップ
  - `/Filename.jpg?type=f&w=100&h=100`
- リサイズ
  - 回転情報がある場合は回転し、「横320、縦320」のフレームに収まるように比率を維持しながら縮小、余白を FFFFFA色で塗りつぶして JPEG quality 95で圧縮
  - `/Filename.jpg?type=m&w=320&h=320&autorotate=true&bgcolor=FFFFFA&quality=95`
- リサイズの後、ウォーターマーク
  - 元の画像がサムネイルより小さい場合は拡大、512x1024に縮小または拡大した後、余白を000011色で塗りつぶす
  - その後、指定の画像 URLを利用し、右上を基準に横11ピクセル、縦10ピクセル移動してウォーターマークを入れる
  - GIFアニメーションの場合、最大100枚に対して同じ作業を実行
  - `/Filename.jpg?type=m_wm&w=512&h=1024&bgcolor=000011&wm_path=http://watermark_URL&wm_offx=11&wm_offy=10&wm_align=2&anilimit=100&extopt=3​`
- リサイズの後、sharpenフィルタを適用、画像の形式を pngに変更
  - `/Filename.jpg?m_sh&w=512&h=256&ttype=png`