API Request Headers:完全入門 (2026年版)
API開発におけるHTTPリクエストヘッダーについて知っておくべきことのすべて
Hyperealで構築を始めよう
Kling、Flux、Sora、Veoなどに単一のAPIでアクセス。無料クレジットで開始、数百万規模まで拡張可能。
クレジットカード不要 • 10万人以上の開発者 • エンタープライズ対応
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を提供しています。
