Unsplash API 実務ガイド：登録・認証・運用まで

2026年5月19日

お得なお知らせ

スポンサードリンク

デザイン本が読み放題

Figma・UI/UX・配色の深いノウハウを

動画・記事の断片情報より、1冊の体系書籍のほうが圧倒的に速い。Kindle Unlimited対象のデザイン書籍が豊富です。

Kindle Unlimited 30日無料▶ Audible｜デザイン発想本を耳で▶

▶ デザイン→エンジニアリングの橋渡しに興味があればプログラミング / エンジニア転職もどうぞ。

タイプ別にすぐ選べる

クリエイティブの引き出し、どう増やす？

Figma・UI/UX・配色・タイポグラフィ。"手を動かす"学びと"発想力を磨く"学びは、使うサブスクが違います。

▷ Figma・UI/UX・配色の具体テクニックを体系化したい実務デザイナー

Kindle Unlimited 30日無料｜デザイン本読み放題▶

▷ ブランド・発想・ディレクション系のインプットを"耳で"増やしたい人

オーディオブックAudible

※無料期間中の解約で料金発生なし

▶ デザイン→エンジニアリングの橋渡しに興味があればプログラミング / エンジニア転職もどうぞ。

Contents

1 概要と対象読者
2 公式規約・料金・参照方法
- 2.1 確認すべき公式ドキュメント
- 2.2 公式ドキュメントで検証すべき項目
3 認証と鍵管理
4 主要エンドポイントとレスポンスの読み方
5 実装サンプル（Next.js / React / Express）
6 運用・監視・コスト最適化
7 代替サービス比較と選定基準
- 7.1 比較表と選定ポイント
8 リリース前チェックリストとクレジット表記テンプレート
- 8.1 リリース前チェックリスト
- 8.2 クレジット表記とロゴ使用のテンプレート
9 まとめ

スポンサードリンク

概要と対象読者

Unsplash API を安全に組み込むための実務手順を短く整理します。登録から認証、検索・表示、運用までの主要ポイントを扱います。
初心者は「認証とハンズオン」から、中級は「主要エンドポイント」と「実装サンプル」を、運用担当は「運用・監視」を優先してお読みください。

公式規約・料金・参照方法

導入判断では公式の利用規約と料金体系の把握が最優先です。API 仕様とブランドガイドは更新され得るため、採用前に必ず公式を参照してください。

確認すべき公式ドキュメント

次の公式ページは導入前に必ず確認してください。仕様やリンクは変更され得ますので注意してください。

https://unsplash.com/documentation
https://unsplash.com/pricing
https://unsplash.com/terms
https://unsplash.com/branding
https://unsplash.com/developers

公式ドキュメントで検証すべき項目

導入前に確認しておくべき代表的項目を列挙します。正式な判定は法務・経理と相談してください。

無料枠の有無と超過課金の計算方法。
API ごとのレート制限（秒間・日次・月次）。
ダウンロードトラッキングの仕様（download_location 等）。
ブランド表記・ロゴ利用規約（明示的テンプレートを確認）。
ダッシュボードでの使用量表示とアラート機能。

注記：上のヘッダー名やエンドポイント挙動は変更されることがあります。実装前に公式を再確認してください。

認証と鍵管理

認証設計はセキュリティと運用コストに直結します。クライアントに秘密鍵を置かないことを原則としてください。

開発者登録と鍵の取り扱い

開発者ポータルでアプリを登録して Access Key と Secret を取得します。Secret はサーバー側のみで保管します。

Access Key（公開可能なアプリ識別子）と Secret（秘密鍵）は用途を分ける。
Secret をクライアントに含めない。クライアント側は自分の API を叩く設計にする。
環境変数やシークレットマネージャーを使う（例：AWS Secrets Manager 等）。
鍵漏洩時は即時ローテーションと影響範囲調査を行う。

OAuth と Bearer トークン（実例と注意点）

ユーザー権限が必要な操作は OAuth を利用します。以下は典型的なフロー例です。実際のパラメータやエンドポイントは公式で確認してください。

認可 URL（例）:
https://unsplash.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=REQUESTED_SCOPES
認可コードを交換してアクセストークンを取得（curl 例）:

curl -X POST &quot;https://unsplash.com/oauth/token&quot; \
  -d &quot;client_id=YOUR_CLIENT_ID&quot; \
  -d &quot;client_secret=YOUR_CLIENT_SECRET&quot; \
  -d &quot;redirect_uri=YOUR_REDIRECT_URI&quot; \
  -d &quot;code=AUTH_CODE&quot; \
  -d &quot;grant_type=authorization_code&quot;

curl -X POST "https://unsplash.com/oauth/token" \

-d "client_id=YOUR_CLIENT_ID" \

-d "client_secret=YOUR_CLIENT_SECRET" \

-d "redirect_uri=YOUR_REDIRECT_URI" \

-d "code=AUTH_CODE" \

-d "grant_type=authorization_code"

API 呼び出し時は Bearer トークンを使用します（例）:

Authorization: Bearer &lt;ACCESS_TOKEN&gt;

1 2	Authorization: Bearer <ACCESS_TOKEN>

注意点：アクセストークンの有効期限やリフレッシュトークンの有無はサービス側の仕様によります。必ず公式を参照して実装してください。

トークン管理とローテーション手順

トークンは短命化と最小権限で運用します。漏洩対応手順を定めておくと迅速に対応できます。

トークンは暗号化して保管する。アクセスは必要最小限にする。
CI/CD のシークレットは専用ストアを利用する。.env を公開しない。
漏洩時の初動：鍵をローテーション、該当トークンの無効化、ログで利用履歴を確認。
ローテーション手順書と復旧手順を文書化する。

主要エンドポイントとレスポンスの読み方

主要エンドポイントの役割と photo オブジェクトの使い分けを明確に理解してください。画像 URL の使い分けとパラメータは UX とコストに影響します。

代表的エンドポイント一覧

よく使うエンドポイントと用途は次の通りです。実際のパスやパラメータは公式で確認してください。

GET https://api.unsplash.com/search/photos — キーワード検索（q, page, per_page 等）
GET https://api.unsplash.com/photos/:id — 写真の詳細取得
GET https://api.unsplash.com/photos/random — ランダム取得（count 指定あり得る）
GET https://api.unsplash.com/collections/:id/photos — コレクション内の写真取得
ユーザー情報やスタッツ、ダウンロード記録用の専用エンドポイント

注記：ダウンロードトラッキングが必須な場合は download_location の利用が必要です。挙動は変更され得るため確認してください。

photo オブジェクトの主要フィールド

レスポンスでよく使うフィールドと目的を整理します。

id：写真 ID。内部保存や参照に使用。
alt_description / description：代替テキストや説明。アクセシビリティに必須。
user：撮影者情報（name、links）。クレジット表示で使用。
urls：画像 URL（raw / full / regular / small / thumb）。用途に応じて選ぶ。
links：API 用リンク（self / html / download / download_location）。

画像 URL のパラメータ指定と注意点（要確認）

URL に ?w=800&q=80&fm=webp のようなパラメータでサイズや品質を指定できます。実装時の注意点は次の通りです。

サムネイルは small または thumb、ギャラリーは regular、詳細は full/raw を使う。
raw は加工用。サーバー側でリサイズや最適化を行う場合に利用。
パラメータや挙動は変更され得ます。必ず公式ドキュメントで最新仕様を確認してください。

実装サンプル（Next.js / React / Express）

クライアントに秘密を渡さないためにサーバープロキシを推奨します。ここでは動作確認手順と安全なサンプルを示します。

最短ハンズオン：ローカルでの動作確認手順

短時間で挙動を確認する手順を示します。各ステップで秘密が漏れないことを確認してください。

開発者ポータルでアプリを作成し Access Key / Secret を取得する。
サンプルリポジトリをクローンする。公式のサンプルを優先して参照する。
環境変数を設定し、Secret はコミットしない。
Next.js 等で API Route を作り、クライアントは自分の API を叩く構成にする。
ダッシュボードで使用量を確認し、課金挙動を把握する。

Next.js API Route の推奨実装（サーバープロキシ）

サーバープロキシはキー漏洩リスクを低減します。以下は安全性を考えた例です。ヘッダー名やバージョンは公式を確認してください。

// pages/api/search.js
export default async function handler(req, res) {
  const { q, page = 1 } = req.query;
  if (!q) return res.status(400).json({ error: 'query required' });

  try {
    const upstream = await fetch(
      `https://api.unsplash.com/search/photos?query=${encodeURIComponent(q)}&amp;page=${encodeURIComponent(page)}&amp;per_page=12`,
      {
        headers: {
          Authorization: `Client-ID ${process.env.UNSPLASH_ACCESS_KEY}`,
          Accept: 'application/json'
          // 参考: 'Accept-Version' を求められる場合があるため公式を確認する
        }
      }
    );

    // レート情報を転送（ヘッダー名は公式で再確認）
    const remaining = upstream.headers.get('x-ratelimit-remaining') || upstream.headers.get('X-Ratelimit-Remaining');
    if (remaining) res.setHeader('X-Upstream-RateLimit-Remaining', remaining);

    const body = await upstream.json();
    return res.status(upstream.status).json(body);
  } catch (err) {
    // ログに秘密情報を出さない
    console.error('Unsplash proxy error:', { message: err.message });
    return res.status(502).json({ error: 'upstream_error' });
  }
}

// pages/api/search.js

export default async function handler(req, res) {

const { q, page = 1 } = req.query;

if (!q) return res.status(400).json({ error: 'query required' });

try {

const upstream = await fetch(

`https://api.unsplash.com/search/photos?query=${encodeURIComponent(q)}&page=${encodeURIComponent(page)}&per_page=12`,

{

headers: {

Authorization: `Client-ID ${process.env.UNSPLASH_ACCESS_KEY}`,

Accept: 'application/json'

// 参考: 'Accept-Version' を求められる場合があるため公式を確認する

}

);

// レート情報を転送（ヘッダー名は公式で再確認）

const remaining = upstream.headers.get('x-ratelimit-remaining') || upstream.headers.get('X-Ratelimit-Remaining');

if (remaining) res.setHeader('X-Upstream-RateLimit-Remaining', remaining);

const body = await upstream.json();

return res.status(upstream.status).json(body);

} catch (err) {

// ログに秘密情報を出さない

console.error('Unsplash proxy error:', { message: err.message });

return res.status(502).json({ error: 'upstream_error' });

}

注記：Accept-Version やレートヘッダーの実際の名前は仕様が変わる可能性があります。実装前に公式を確認してください。

フロントエンド表示：HTML と React (JSX) の正しい書き方

クライアントは自分の API を叩き、JSX 側で正しくレンダーします。以下は HTML と JSX の例です。

&lt;!-- HTML の例（静的テンプレートやサーバー側レンダリング） --&gt;
&lt;img
  src=&quot;/api/images/serve?size=small&amp;id=PHOTO_ID&quot;
  srcset=&quot;/api/images/serve?size=small&amp;id=PHOTO_ID 400w, /api/images/serve?size=regular&amp;id=PHOTO_ID 800w, /api/images/serve?size=full&amp;id=PHOTO_ID 1200w&quot;
  sizes=&quot;(min-width:1024px) 33vw, 50vw&quot;
  alt=&quot;撮影者による説明&quot;
  loading=&quot;lazy&quot;
/&gt;

<img

src="/api/images/serve?size=small&id=PHOTO_ID"

srcset="/api/images/serve?size=small&id=PHOTO_ID 400w, /api/images/serve?size=regular&id=PHOTO_ID 800w, /api/images/serve?size=full&id=PHOTO_ID 1200w"

sizes="(min-width:1024px) 33vw, 50vw"

alt="撮影者による説明"

loading="lazy"

// React (JSX) の例
function Photo({ photo }) {
  return (
    &lt;img
      src={photo.urls.small}
      srcSet={`${photo.urls.small} 400w, ${photo.urls.regular} 800w, ${photo.urls.full} 1200w`}
      sizes=&quot;(min-width:1024px) 33vw, 50vw&quot;
      alt={photo.alt_description || photo.description || 'photo'}
      loading=&quot;lazy&quot;
      decoding=&quot;async&quot;
    /&gt;
  );
}

// React (JSX) の例

function Photo({ photo }) {

return (

<img

src={photo.urls.small}

srcSet={`${photo.urls.small} 400w, ${photo.urls.regular} 800w, ${photo.urls.full} 1200w`}

sizes="(min-width:1024px) 33vw, 50vw"

alt={photo.alt_description || photo.description || 'photo'}

loading="lazy"

decoding="async"

);

}

フロントエンドは必ず自前の API を経由し、直接 Access Key や Secret を埋め込まないでください。

運用・監視・コスト最適化

運用ではメトリクス収集とアラート設定が重要です。費用増加は早期に検知できる体制を作ってください。

主要メトリクスと推奨アラート閾値

監視対象とサンプルクエリを示します。閾値はサービス規模に合わせて調整してください。

監視対象例：リクエスト数、5xx エラー率、429 発生数、レート残量、レイテンシ（P95）、推定請求額。
Prometheus サンプル（実装は独自のメトリクス名で行う）:

# 総リクエスト数（5分レート）
sum(rate(unsplash_requests_total[5m]))

# 5xx エラー率が 1% を超えたらアラート
(sum(rate(unsplash_requests_total{status=~&quot;5..&quot;}[5m])) / sum(rate(unsplash_requests_total[5m]))) &gt; 0.01

# 429 が急増したらアラート（5分で増加が 5 件を超える等）
increase(unsplash_requests_total{status=&quot;429&quot;}[5m]) &gt; 5

# レート残量が少ない場合（レート上限を取り込んでいる場合）
unsplash_rate_limit_remaining &lt; 100

# 総リクエスト数（5分レート）

sum(rate(unsplash_requests_total[5m]))

# 5xx エラー率が 1% を超えたらアラート

(sum(rate(unsplash_requests_total{status=~"5.."}[5m])) / sum(rate(unsplash_requests_total[5m]))) > 0.01

# 429 が急増したらアラート（5分で増加が 5 件を超える等）

increase(unsplash_requests_total{status="429"}[5m]) > 5

# レート残量が少ない場合（レート上限を取り込んでいる場合）

unsplash_rate_limit_remaining < 100

推奨閾値の例：エラー率 0.5〜1%（5 分継続）で警告、429 の急増（5 分で 5 回以上）で緊急対応、請求は月予算の 50% と 80% にアラート。

ログ、エラーハンドリング、セキュリティ運用

ログは調査に有用な情報を残しつつ、機密情報を除外することが重要です。

Authorization ヘッダーやトークンはログに絶対残さない。トークンはハッシュ化して検査する。
構造化ログ（JSON）を使い、追跡 ID を付与する。
CORS は必要最小限のオリジンに限定する。
CSP で画像ソースを制限する（例: img-src 'self' https://images.unsplash.com 等）。
インシデント初動：トークン無効化→鍵ローテーション→ログ保存→影響範囲通知。フォレンジック用にログの保全を行う。

コスト削減の実践テクニック

API コールを削減するとコストとレート消費を抑えられます。

CDN とエッジキャッシュを活用し、同一画像の再取得を防ぐ。
サムネイルは事前生成してキャッシュする。動的パラメータは最小化する。
必要なメタデータのみ取得する（不要なフィールドは除外）。
高トラフィック時はキャッシュ TTL を一時的に延長する運用ルールを用意する。

代替サービス比較と選定基準

Unsplash 以外のサービスとの比較で選定基準を明確にしてください。API 性能とライセンスが意思決定において重要です。

比較表と選定ポイント

以下は概観です。各項目は実際の導入前に最新情報を確認してください。

サービス	ライセンス概況	無料枠	API 機能	商用/エンタープライズ向け
Unsplash	商用利用が可能な高品質画像（要確認）	有り／条件あり（要確認）	検索・ランダム・ダウンロードトラッキング	中小〜企業向けプランあり
Pexels	商用利用可能（要確認）	比較的寛容	検索、ダウンロード	中小向けに使いやすい
Pixabay	商用利用可能（要確認）	フリー枠豊富	基本的な画像検索	コスト重視の導入向け
Getty / Shutterstock	ライセンス明確だが有償	低い／有償	高精度検索・エンタープライズサポート	大規模商用に適合

選定時は「ライセンスの明確さ」「API の機能」「価格」「商用サポート」を重み付けして比較してください。

リリース前チェックリストとクレジット表記テンプレート

リリース前に実務的なチェックを済ませておくとトラブルを減らせます。ブランド表記は法務と最終確認を行ってください。

リリース前チェックリスト

実運用前に最低限確認すべき項目を列挙します。

公式利用規約と料金を確認済みか。
請求アラート（例：月額予算の 50% / 80%）を設定しているか。
レート制限対策（リトライ、指数バックオフ、キャッシュ）を実装済みか。
CDN / キャッシュの動作検証を行ったか。
ダウンロードトラッキングの実装とログが動作するか。
クレジット表記とロゴ利用の承認を法務／デザイナーから得ているか。
監視とインシデント対応手順を周知しているか。

クレジット表記とロゴ使用のテンプレート

法務・デザイナーがそのまま使えるような文言例を示します。最終的には公式のブランドガイドラインに従ってください。

写真ごとのクレジット（簡易・写真横）:
写真：John Doe / Unsplash（リンク先: https://unsplash.com/photos/PHOTO_ID）
写真ごとのクレジット（英語例）:
Photo by John Doe on Unsplash
HTML 例: Photo by John Doe on Unsplash
フッターの一般表記例（サイト全体）:
Images provided by Unsplash. （または日本語で「画像提供：Unsplash」）
ロゴ利用の基本テンプレート（デザイナー向け）:
変更禁止：ロゴの色・比率を変更しない。
クリアスペース：ロゴの高さの 0.5 倍を左右に確保する等、具体値はブランドガイドに従う。
最小表示サイズ：高さ 24px を下限の目安とする（デザインにより調整）。