Zenn
🐥

Cloudflare Images 画像アップロード・インポート方法

2025/02/25に公開
Cloudflare
images
tech

Cloudflare Images の補足情報です。

対象は Store です。
外部（R2 含む）のオリジンから画像を読んでリサイズなどを行う Transform は範囲外です。

画像のアップロード方法について書くので、画像の管理・加工・配送などは触れません。

アップロードの方法は大きく 4 つです。

方法 作業者
ダッシュボード 管理者
API 管理者
ダイレクトクリエーターアップロード 管理者以外
例：クリエーター
ソーシングキット 管理者
S3 bucket から自動インポート

前提

執筆時点（2025 年 2 月）
画像フォーマット

フォーマット 対応
PNG ✓
GIF ✓
JPEG ✓
WebP ✓
SVG ✓
HEIC
(HEIF)		 未サポート

ディメンションとサイズ

項目 制限値
Maximum image dimension 12,000 pixels
Maximum image area 100 megapixels
(for example, 10,000×10,000 pixels)
Image metadata limited to 1024 bytes
Image size 10 megabyte (MB) size limit
Animated GIFs/WebP
including all frames		 limited to 50 megapixels (MP)

ダッシュボード

ファイルをドラッグアンドドロップします。

API

Images 管理用の API トークンを作っておきます。

cURL ならダッシュボードからコマンドを作れます。
API トークンとイメージファイル名（手元の）を入れると、コマンド作ってくれます。

API パラメータ

アップロード用 API のパラメータは下記になります。

フォームデータ 内容
file / url 画像ソース
requireSignedURLs 署名付き URL でのみ公開する
metadata 管理用メタデータ（eyeball には伝達されない）

画像は file 以外に url から渡すことができます。どっちかです。

Keep in mind that the --form 'file=<FILE>' and --form 'url=<URL>' fields are mutually exclusive.

アップロード例
curl --request POST \
"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/images/v1" \
--header "Authorization: Bearer $API_TOKEN" \
--form "url=$SRC_URL" \
--form 'metadata={"key":"value"}' \
--form 'requireSignedURLs=false'

API (batch)

API にはリクエスト制限 1200 リクエスト / 5 分 があります。（ Enterprise plan は引き上げ可能）

The global rate limit for the Cloudflare API is 1200 requests per five minute period per user, and applies cumulatively regardless of whether the request is made via the dashboard, API key, or API token.

それを回避するエンドポイント batch API が用意されています。
batch API 用のトークン（JWT）一つにつき、200 リクエスト/秒 が可能になります。
複数の JWT を並行利用し、転送量を増やすことができます。

Each token is subject to a rate limit of 200 requests per second. You can use multiple tokens if you require higher throughput to the Cloudflare Images API.

エンドポイントの Hostname は batch.imagedelivery.net になり、下記のパスを取ります。

まず batch API 用の JWT を得ます。

Token 入手
$ curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/images/v1/batch_token" \
--header "Authorization: Bearer $API_TOKEN"

{
  "result": {
    "token": "JWT",
    "expiresAt": "期限"
  },
  "success": true,
  "errors": [],
  "messages": []
}

戻り値を見ると expiresAt の期限は 1 時間の模様です。（dev docs 見つけられず）

得た JWT を Bearer に指定して画像をアップロードします。
前述のとおり、アップロードの場合 https://batch.imagedelivery.net/images/v1 に POST します。

アップロード例
curl --request POST \
"https://batch.imagedelivery.net/images/v1" \
--header "Authorization: Bearer $BATCH_TOKEN" \
--form "url=$SRC_URL"

ダイレクトクリエーターアップロード

Direct Creator Upload は API トークンを利用せず、アップロード用の一時的な URL を発行します。
画像のアップロードを管理者以外に委任可能になります。

管理者はダイレクトアップロード用の URL を発行します。
uploadURL の有効期間はデフォルト 30 分で、2 分 ~ 6 時間の間で指定可能（expiry）です。

URL 入手
$ curl --request POST \
"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/images/v2/direct_upload" \
--header "Authorization: Bearer $API_TOKEN"

{
"result": {
 "id": "8e4d8066-024c-475c-38f2-6fe838b8c500",
 "uploadURL": "https://upload.imagedelivery.net/_M.../8..."
},
"success": true,
"errors": [],
"messages": []
}%

uploadURL は https://upload.imagedelivery.net/アカウント ID ハッシュ/イメージ ID になります。
ユーザーはそこに画像データをアップロードします。

アップロード例
curl --request POST \
"$UPLOAD_URL" \
--form "url=$SRC_URL"

通知設定をすると、管理者がアップロードの通知を受け取ることもできます。

ソーシングキット

Sourcing Kit はクラウドストレージから直接インポートします。
執筆時点（2025 年 2 月）では Beta ですが、 Amazon S3 に対応しています。IAM の S3 Get / List 権限が必要です。
なお S3 Glacier tiers (not including Glacier Instant Retrieval) と S3 Intelligent Tiering and placed in Deep Archive tier は対象とならずスキップされます。

👉️ インポート開始

👉️ Step 1（ソース指定）

👉️ Step 2（インポートのルール：配信パスの指定など）

👉️ Step 3（設定確認と実行）

👉️ Step 4（インポート状況の確認）


👉️ Step 5（インポートされた画像）

ユーザー（eyeball）からの接続（カスタムパスのオプション）

ユーザー（eyeball）からの接続 URL は下記のとおりです。
Custom Path のオプションが可能です。

scheme host path 補足
https imagedelivery.net /アカウント ID ハッシュ/イメージ ID/バリアント名 -
https アカウント配下のプロキシーされたホスト /cdn-cgi/imagedelivery/アカウント ID ハッシュ/イメージ ID/バリアント名 -
https アカウント配下のプロキシーされたホスト /cdn-cgi/imagedelivery/アカウント ID ハッシュ/カスタム ID/バリアント名 動的採番のイメージ ID の代わりに任意のカスタム ID を指定。
一方 signed_url が利用できなくなる

応用として、ユーザーに見せる URL を簡素化する（/cdn-cgi/imagedelivery/を削る）例がありました。Transform Rules を使っています。

ユーザーに見せる path Images に渡す path（ Transform Rules 適用後）
/img/カスタム ID/バリアント名 /cdn-cgi/imagedelivery/アカウント ID ハッシュ/カスタム ID/バリアント名

URL 変換は Transform Rules や Workers を使えば色々工夫ができそうです。

画像ソースを Workers AI で遊ぶ

Workers AI との組み合わせのアイデアがありましたので、試します。

下記のように、生成された画像を一回こっきりで直接で渡すのではなく、

Images に画像の保管と配送を依頼するパターンです。

Worker
import { Hono } from 'hono'
import { Ai } from '@cloudflare/ai'

export interface Env {
	AI: any
	IMAGES_URL: string
	API_TOKEN: string
}

const app = new Hono<{ Bindings:Env }>()

app.get('/', async c => {
	const ai = new Ai(c.env.AI)
	const content = c.req.query('q') || 'cyberpunk dog'
	const inputs = {
		prompt: content,
	};
	const stream = await ai.run(
		'@cf/bytedance/stable-diffusion-xl-lightning',
		inputs
	);

	// stream to bytes
	const bytes = await (new Response(stream)).arrayBuffer()

	// form data with the image
	const now = Date.now()
	const fname = content+'_'+now
	const formData = new FormData()
	formData.append('file', new File([ bytes ], fname+'.jpg', { type: 'image/jpg' }))
	formData.append('metadata','{"src":"workers-ai"}')
	formData.append('id',fname)
	const response =  await fetch(
		c.env.IMAGES_URL,
		{
			method: 'POST',
			headers: {
				'Authorization': `Bearer ${c.env.API_TOKEN}`
			},
			body: formData
		}
	)
	const result = (await response.json()) as any
	return c.json(result)
})

export default app
実行結果
$ http -b localhost:8787 q=="ラーメン半チャーハン"

{
    "errors": [],
    "messages": [],
    "result": {
        "filename": "ラーメン半チャーハン_1740400993699.jpg",
        "id": "ラーメン半チャーハン_1740400993699",
        "meta": {
            "src": "workers-ai"
        },
        "requireSignedURLs": false,
        "uploaded": "2025-02-24T12:43:15.430Z",
        "variants": [
            "https://imagedelivery.net/_M.../ラーメン半チャーハン_1740400993699/header",
            "https://imagedelivery.net/_M.../ラーメン半チャーハン_1740400993699/test1",
            :
        ]
    },
    "success": true
}

ブラウザーでhttps://imagedelivery.net/_M.../ラーメン半チャーハン_1740400993699/test1 を開くとラーメン半チャーハン で SDXL-Lightning に注文した画像が Images から配信されました。

半チャーハンどこだ...?

以上、Cloudflare Images へのアップロード方法でした。

Discussion