API Request Headers：完全入門 (2026年版)

API Request Headers: 完全ガイド (2026年版)

HTTPリクエストヘッダーは、クライアントが全てのAPIリクエストとともにサーバーに送信するキーと値のペアです。これらはリクエストに関するメタデータ（データの形式、リクエストの送信者、許容されるレスポンス形式、サーバーによるキャッシュ、セキュリティ、ルーティングの処理方法など）を伝達します。

APIを構築または利用する場合、リクエストヘッダーを理解することは不可欠です。本ガイドでは、最も重要なヘッダー、それを使用すべきタイミング、そして cURL、Python、JavaScript による実践的なコード例を解説します。

リクエストヘッダーとは？

全てのHTTPリクエストは、以下の3つの部分で構成されています。

リクエストライン (Request line): メソッド（GET、POSTなど）とURL。
ヘッダー (Headers): リクエストに関するキーと値のメタデータ。
ボディ (Body): データペイロード（POST、PUT、PATCHリクエスト用）。

以下は、これら3つの要素を含む生のHTTPリクエストの例です。

POST /api/v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Accept: application/json
User-Agent: MyApp/1.0
Content-Length: 52

{"name": "Alice", "email": "alice@example.com"}

リクエストラインとボディの間の行がヘッダーです。各ヘッダーは、コロンで区切られた名前と値で構成されています。

必須のリクエストヘッダー

Content-Type

サーバーに対して、リクエストボディの形式を伝えます。

値	使用するタイミング
`application/json`	ほとんどのREST API
`application/x-www-form-urlencoded`	HTMLフォーム送信、OAuthトークンリクエスト
`multipart/form-data`	ファイルアップロード
`text/plain`	プレーンテキストのペイロード
`application/xml`	XMLベースのAPI (SOAP、一部のエンタープライズAPI)
`application/octet-stream`	未加工のバイナリデータ

例: JSONリクエスト

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

例: フォームエンコードリクエスト

curl -X POST https://auth.example.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=abc&client_secret=xyz"

例: ファイルアップロード

curl -X POST https://api.example.com/upload \
  -H "Content-Type: multipart/form-data" \
  -F "file=@photo.jpg" \
  -F "description=Profile photo"

よくある間違いは、Content-Type として application/json を送信しながら、ボディにフォームエンコードされたデータを送る（またはその逆）ことです。Content-Type が実際のボディ形式と一致しない場合、サーバーは 400 または 415 エラーを返します。

Authorization

呼び出し元を特定し、保護されたリソースへのアクセスを許可します。

スキーム	フォーマット	ユースケース
Bearer	`Bearer <token>`	OAuth 2.0、JWTベースのAPI
Basic	`Basic <base64(user:pass)>`	シンプルなAPIキー認証
API Key	`X-API-Key: <key>`	独自API（カスタムヘッダー）
Digest	`Digest <params>`	レガシーシステム

Bearerトークン（最も一般的）:

import requests

response = requests.get(
    "https://api.example.com/users/me",
    headers={
        "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    },
)

Basic認証:

import requests

response = requests.get(
    "https://api.example.com/data",
    auth=("username", "password"),  # requestsがBase64エンコードを処理します
)

カスタムヘッダーによるAPIキー:

response = requests.get(
    "https://api.example.com/data",
    headers={
        "X-API-Key": "your-api-key-here"
    },
)

Accept

受け取りたいレスポンス形式をサーバーに伝えます。

# JSONレスポンスを要求
curl -H "Accept: application/json" https://api.example.com/data

# XMLレスポンスを要求（APIが対応している場合）
curl -H "Accept: application/xml" https://api.example.com/data

# 優先順位（品質係数）を指定して複数の形式を許容
curl -H "Accept: application/json;q=0.9, text/html;q=0.8" https://api.example.com/data

q パラメータ（品質係数）は、0から1の範囲で優先度を示します。サーバーが複数の形式をサポートしている場合、最も品質係数の高いものが選択されます。

User-Agent

リクエストを行っているクライアントを特定します。常に必須というわけではありませんが、多くのAPIで分析、レート制限、デバッグに使用されます。

headers = {
    "User-Agent": "MyApp/2.0 (Python 3.12; Linux x86_64)"
}

一部のAPIは、User-Agent ヘッダーがないリクエストや、汎用的なライブラリのデフォルト値のリクエストを拒否します。プロダクション環境のアプリケーションでは、必ず説明的な User-Agent を設定してください。

キャッシュヘッダー

適切なキャッシュヘッダーを使用することで、サーバーの負荷を軽減し、レスポンス時間を短縮できます。

Cache-Control (リクエスト)

ディレクティブ	意味
`no-cache`	キャッシュされたレスポンスを使用する前にサーバーで検証する
`no-store`	レスポンスを一切キャッシュしない
`max-age=0`	キャッシュされたレスポンスを期限切れとして扱う
`only-if-cached`	キャッシュされたレスポンスのみを返す。キャッシュにない場合は失敗させる

# キャッシュをバイパスし、最新のレスポンスを強制する
curl -H "Cache-Control: no-cache" https://api.example.com/data

If-None-Match / If-Modified-Since

これらは、効率的なキャッシュを可能にする条件付きリクエストヘッダーです。

# 初回リクエスト：サーバーはレスポンスで ETag を返します
response = requests.get("https://api.example.com/data")
etag = response.headers.get("ETag")

# 次回以降のリクエスト：ETag を送り返します
response = requests.get(
    "https://api.example.com/data",
    headers={"If-None-Match": etag},
)

if response.status_code == 304:
    print("データに変更はありません。キャッシュ版を使用します。")
else:
    print("データが更新されました。新しいレスポンスを処理します。")

これにより、データに変更がない場合にフルレスポンスボディの転送を回避でき、帯域幅の節約とレイテンシの削減が可能になります。

CORS ヘッダー

Cross-Origin Resource Sharing (CORS) ヘッダーは、ブラウザベースの JavaScript アプリケーションが異なるドメインの API を呼び出す際に関連します。

プリフライトリクエストヘッダー

ブラウザがプリフライト（OPTIONS）リクエストを送信する際、以下が含まれます。

ヘッダー	目的
`Origin`	リクエストを行っているドメイン
`Access-Control-Request-Method`	実際のリクエストで使用される HTTP メソッド
`Access-Control-Request-Headers`	実際のリクエストに含まれるカスタムヘッダー

これらをエンジニアが手動で設定することはありません。ブラウザが自動的に追加します。ただし、これらを理解しておくことは CORS の問題のデバッグに役立ちます。

一般的な CORS デバッグチェックリスト

ブラウザのコンソールで、正確な CORS エラーメッセージを確認する。
サーバーのレスポンスに含まれる Access-Control-Allow-Origin ヘッダーが、自身のドメインと一致しているか（または * であるか）を検証する。
Authorization のようなカスタムヘッダーを送信している場合、サーバーがそれらを Access-Control-Allow-Headers に含めている必要がある。
サーバーが認証情報を必要とする（Credentials）場合、Access-Control-Allow-Credentials: true と、具体的な（* ではない）ドメインの指定の両方が必要。

レート制限ヘッダー

APIはヘッダーを使用して、レート制限の状態を伝えます。

ヘッダー	意味
`X-RateLimit-Limit`	指定期間内に許可される最大リクエスト数
`X-RateLimit-Remaining`	現在の期間内に残っているリクエスト数
`X-RateLimit-Reset`	制限がリセットされるタイミング（Unixタイムスタンプ）
`Retry-After`	再試行するまで待機する秒数（429レスポンスとともに送信される）

Python でのレート制限の処理:

import time
import requests

def make_request(url, headers):
    response = requests.get(url, headers=headers)

    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 60))
        print(f"レート制限にかかりました。{retry_after}秒待機します...")
        time.sleep(retry_after)
        return make_request(url, headers)  # 再試行

    remaining = response.headers.get("X-RateLimit-Remaining")
    if remaining and int(remaining) < 10:
        print(f"警告: 残りリクエスト数はあと{remaining}回です")

    return response

リクエスト ID とトレースヘッダー

分散システムのデバッグのために、リクエストトレースヘッダーを含めます。

ヘッダー	目的
`X-Request-ID`	リクエストの一意の識別子（ログの関連付け用）
`X-Correlation-ID`	サービス間呼び出しをまたいで維持されるトレース ID
`Traceparent`	W3C 標準のトレースコンテキストヘッダー

import uuid

headers = {
    "X-Request-ID": str(uuid.uuid4()),
    "X-Correlation-ID": "user-session-abc-123",
}

多くの API プロバイダーは、レスポンスにリクエスト ID を含めて返します。この値は必ずログに記録してください。プロバイダーのサポートチームに問題を問い合わせる際に不可欠となります。

各言語でのヘッダー設定方法

Python (requests)

import requests

response = requests.post(
    "https://api.example.com/data",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer your-token",
        "Accept": "application/json",
        "X-Request-ID": "req-12345",
    },
    json={"key": "value"},  # 自動的に Content-Type を application/json に設定します
)

注意: requests.post() で json パラメータを使用すると、ライブラリは自動的に Content-Type: application/json を設定します。その場合、手動で設定する必要はありません。

JavaScript (fetch)

const response = await fetch("https://api.example.com/data", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer your-token",
    "Accept": "application/json",
  },
  body: JSON.stringify({ key: "value" }),
});

JavaScript (axios)

import axios from "axios";

// 全てのリクエストのデフォルトヘッダーを設定
axios.defaults.headers.common["Authorization"] = "Bearer your-token";
axios.defaults.headers.post["Content-Type"] = "application/json";

// あるいはリクエストごとに設定
const response = await axios.post(
  "https://api.example.com/data",
  { key: "value" },
  {
    headers: {
      "X-Custom-Header": "custom-value",
    },
  }
);

cURL

curl -X POST https://api.example.com/data \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -H "Accept: application/json" \
  -H "X-Request-ID: req-12345" \
  -d '{"key": "value"}'

クイックリファレンステーブル

ヘッダー	必須？	例	目的
`Content-Type`	ボディがある場合は必須	`application/json`	リクエストボディの形式
`Authorization`	保護されたエンドポイントに必須	`Bearer eyJ...`	認証
`Accept`	推奨	`application/json`	希望するレスポンス形式
`User-Agent`	推奨	`MyApp/1.0`	クライアントの識別
`Cache-Control`	任意	`no-cache`	キャッシュの動作
`If-None-Match`	任意	`"etag-value"`	条件付きリクエスト
`Origin`	自動（ブラウザ）	`https://myapp.com`	CORS
`X-Request-ID`	推奨	`uuid-value`	リクエストのトレース

まとめ

HTTP API を利用する上で、リクエストヘッダーの理解は不可欠です。まず覚えるべき最も重要なものは、Content-Type（送信するデータ）、Authorization（誰であるか）、Accept（何を受け取りたいか）の3つです。アプリケーションの複雑さが増すにつれて、キャッシュヘッダー、CORS ヘッダー、レート制限ヘッダーなどが重要になってきます。

画像、ビデオ、トーキングアバター、オーディオなどのAIメディア生成APIを利用したアプリケーションを構築している方は、ぜひ Hypereal AI を確認してください。Hypereal は、シンプルな認証ヘッダーと最新の生成AIモデル向けの従量課金制を備えた統合APIを提供しています。

API Request Headers: 完全ガイド (2026年版)

リクエストヘッダーとは？

全てのHTTPリクエストは、以下の3つの部分で構成されています。

リクエストライン (Request line): メソッド（GET、POSTなど）とURL。
ヘッダー (Headers): リクエストに関するキーと値のメタデータ。
ボディ (Body): データペイロード（POST、PUT、PATCHリクエスト用）。

以下は、これら3つの要素を含む生のHTTPリクエストの例です。

POST /api/v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Accept: application/json
User-Agent: MyApp/1.0
Content-Length: 52

{"name": "Alice", "email": "alice@example.com"}

リクエストラインとボディの間の行がヘッダーです。各ヘッダーは、コロンで区切られた名前と値で構成されています。

必須のリクエストヘッダー

Content-Type

サーバーに対して、リクエストボディの形式を伝えます。

値	使用するタイミング
`application/json`	ほとんどのREST API
`application/x-www-form-urlencoded`	HTMLフォーム送信、OAuthトークンリクエスト
`multipart/form-data`	ファイルアップロード
`text/plain`	プレーンテキストのペイロード
`application/xml`	XMLベースのAPI (SOAP、一部のエンタープライズAPI)
`application/octet-stream`	未加工のバイナリデータ

例: JSONリクエスト

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

例: フォームエンコードリクエスト

curl -X POST https://auth.example.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=abc&client_secret=xyz"

例: ファイルアップロード

curl -X POST https://api.example.com/upload \
  -H "Content-Type: multipart/form-data" \
  -F "file=@photo.jpg" \
  -F "description=Profile photo"

Authorization

呼び出し元を特定し、保護されたリソースへのアクセスを許可します。

スキーム	フォーマット	ユースケース
Bearer	`Bearer <token>`	OAuth 2.0、JWTベースのAPI
Basic	`Basic <base64(user:pass)>`	シンプルなAPIキー認証
API Key	`X-API-Key: <key>`	独自API（カスタムヘッダー）
Digest	`Digest <params>`	レガシーシステム

Bearerトークン（最も一般的）:

import requests

response = requests.get(
    "https://api.example.com/users/me",
    headers={
        "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    },
)

Basic認証:

import requests

response = requests.get(
    "https://api.example.com/data",
    auth=("username", "password"),  # requestsがBase64エンコードを処理します
)

カスタムヘッダーによるAPIキー:

response = requests.get(
    "https://api.example.com/data",
    headers={
        "X-API-Key": "your-api-key-here"
    },
)

Accept

受け取りたいレスポンス形式をサーバーに伝えます。

# JSONレスポンスを要求
curl -H "Accept: application/json" https://api.example.com/data

# XMLレスポンスを要求（APIが対応している場合）
curl -H "Accept: application/xml" https://api.example.com/data

# 優先順位（品質係数）を指定して複数の形式を許容
curl -H "Accept: application/json;q=0.9, text/html;q=0.8" https://api.example.com/data

User-Agent

headers = {
    "User-Agent": "MyApp/2.0 (Python 3.12; Linux x86_64)"
}

キャッシュヘッダー

適切なキャッシュヘッダーを使用することで、サーバーの負荷を軽減し、レスポンス時間を短縮できます。

Cache-Control (リクエスト)

ディレクティブ	意味
`no-cache`	キャッシュされたレスポンスを使用する前にサーバーで検証する
`no-store`	レスポンスを一切キャッシュしない
`max-age=0`	キャッシュされたレスポンスを期限切れとして扱う
`only-if-cached`	キャッシュされたレスポンスのみを返す。キャッシュにない場合は失敗させる

# キャッシュをバイパスし、最新のレスポンスを強制する
curl -H "Cache-Control: no-cache" https://api.example.com/data

If-None-Match / If-Modified-Since

これらは、効率的なキャッシュを可能にする条件付きリクエストヘッダーです。

# 初回リクエスト：サーバーはレスポンスで ETag を返します
response = requests.get("https://api.example.com/data")
etag = response.headers.get("ETag")

# 次回以降のリクエスト：ETag を送り返します
response = requests.get(
    "https://api.example.com/data",
    headers={"If-None-Match": etag},
)

if response.status_code == 304:
    print("データに変更はありません。キャッシュ版を使用します。")
else:
    print("データが更新されました。新しいレスポンスを処理します。")

これにより、データに変更がない場合にフルレスポンスボディの転送を回避でき、帯域幅の節約とレイテンシの削減が可能になります。

CORS ヘッダー

Cross-Origin Resource Sharing (CORS) ヘッダーは、ブラウザベースの JavaScript アプリケーションが異なるドメインの API を呼び出す際に関連します。

プリフライトリクエストヘッダー

ブラウザがプリフライト（OPTIONS）リクエストを送信する際、以下が含まれます。

ヘッダー	目的
`Origin`	リクエストを行っているドメイン
`Access-Control-Request-Method`	実際のリクエストで使用される HTTP メソッド
`Access-Control-Request-Headers`	実際のリクエストに含まれるカスタムヘッダー

一般的な CORS デバッグチェックリスト

ブラウザのコンソールで、正確な CORS エラーメッセージを確認する。
サーバーのレスポンスに含まれる Access-Control-Allow-Origin ヘッダーが、自身のドメインと一致しているか（または * であるか）を検証する。
Authorization のようなカスタムヘッダーを送信している場合、サーバーがそれらを Access-Control-Allow-Headers に含めている必要がある。
サーバーが認証情報を必要とする（Credentials）場合、Access-Control-Allow-Credentials: true と、具体的な（* ではない）ドメインの指定の両方が必要。

レート制限ヘッダー

APIはヘッダーを使用して、レート制限の状態を伝えます。

ヘッダー	意味
`X-RateLimit-Limit`	指定期間内に許可される最大リクエスト数
`X-RateLimit-Remaining`	現在の期間内に残っているリクエスト数
`X-RateLimit-Reset`	制限がリセットされるタイミング（Unixタイムスタンプ）
`Retry-After`	再試行するまで待機する秒数（429レスポンスとともに送信される）

Python でのレート制限の処理:

import time
import requests

def make_request(url, headers):
    response = requests.get(url, headers=headers)

    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 60))
        print(f"レート制限にかかりました。{retry_after}秒待機します...")
        time.sleep(retry_after)
        return make_request(url, headers)  # 再試行

    remaining = response.headers.get("X-RateLimit-Remaining")
    if remaining and int(remaining) < 10:
        print(f"警告: 残りリクエスト数はあと{remaining}回です")

    return response

リクエスト ID とトレースヘッダー

分散システムのデバッグのために、リクエストトレースヘッダーを含めます。

ヘッダー	目的
`X-Request-ID`	リクエストの一意の識別子（ログの関連付け用）
`X-Correlation-ID`	サービス間呼び出しをまたいで維持されるトレース ID
`Traceparent`	W3C 標準のトレースコンテキストヘッダー

import uuid

headers = {
    "X-Request-ID": str(uuid.uuid4()),
    "X-Correlation-ID": "user-session-abc-123",
}

各言語でのヘッダー設定方法

Python (requests)

import requests

response = requests.post(
    "https://api.example.com/data",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer your-token",
        "Accept": "application/json",
        "X-Request-ID": "req-12345",
    },
    json={"key": "value"},  # 自動的に Content-Type を application/json に設定します
)

JavaScript (fetch)

const response = await fetch("https://api.example.com/data", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer your-token",
    "Accept": "application/json",
  },
  body: JSON.stringify({ key: "value" }),
});

JavaScript (axios)

import axios from "axios";

// 全てのリクエストのデフォルトヘッダーを設定
axios.defaults.headers.common["Authorization"] = "Bearer your-token";
axios.defaults.headers.post["Content-Type"] = "application/json";

// あるいはリクエストごとに設定
const response = await axios.post(
  "https://api.example.com/data",
  { key: "value" },
  {
    headers: {
      "X-Custom-Header": "custom-value",
    },
  }
);

cURL

curl -X POST https://api.example.com/data \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -H "Accept: application/json" \
  -H "X-Request-ID: req-12345" \
  -d '{"key": "value"}'

クイックリファレンステーブル

ヘッダー	必須？	例	目的
`Content-Type`	ボディがある場合は必須	`application/json`	リクエストボディの形式
`Authorization`	保護されたエンドポイントに必須	`Bearer eyJ...`	認証
`Accept`	推奨	`application/json`	希望するレスポンス形式
`User-Agent`	推奨	`MyApp/1.0`	クライアントの識別
`Cache-Control`	任意	`no-cache`	キャッシュの動作
`If-None-Match`	任意	`"etag-value"`	条件付きリクエスト
`Origin`	自動（ブラウザ）	`https://myapp.com`	CORS
`X-Request-ID`	推奨	`uuid-value`	リクエストのトレース

Hyperealで構築を始めよう

API Request Headers: 完全ガイド (2026年版)

リクエストヘッダーとは？

必須のリクエストヘッダー

Content-Type

Authorization

Accept

User-Agent

キャッシュヘッダー

Cache-Control (リクエスト)

If-None-Match / If-Modified-Since

CORS ヘッダー

プリフライトリクエストヘッダー

一般的な CORS デバッグチェックリスト

レート制限ヘッダー

リクエスト ID とトレースヘッダー

各言語でのヘッダー設定方法

Python (requests)

JavaScript (fetch)

JavaScript (axios)

cURL

クイックリファレンステーブル

まとめ

関連記事

HTTP Content-Type ヘッダー：完全ガイド (2026年版)

HTTP DELETE メソッド：完全ガイド (2026年版)

GET vs POST：その違いとは？ (2026年版)

今日から構築を開始

Hyperealで構築を始めよう

API Request Headers: 完全ガイド (2026年版)

リクエストヘッダーとは？

必須のリクエストヘッダー

Content-Type

Authorization

Accept

User-Agent

キャッシュヘッダー

Cache-Control (リクエスト)

If-None-Match / If-Modified-Since

CORS ヘッダー

プリフライトリクエストヘッダー

一般的な CORS デバッグチェックリスト

レート制限ヘッダー

リクエスト ID とトレースヘッダー

各言語でのヘッダー設定方法

Python (requests)

JavaScript (fetch)

JavaScript (axios)

cURL

クイックリファレンステーブル

まとめ

関連記事

HTTP Content-Type ヘッダー：完全ガイド (2026年版)

HTTP DELETE メソッド：完全ガイド (2026年版)

GET vs POST：その違いとは？ (2026年版)

今日から構築を開始