API Request Headers：完整指南 (2026)

API 请求头：详尽指南 (2026)

HTTP 请求头（Request Headers）是客户端在进行每次 API 请求时发送给服务器的键值对。它们携带了关于请求的元数据——例如数据是什么格式、谁发起的请求、可以接受什么样的响应格式，以及服务器应该如何处理缓存、安全和路由。

无论你是在构建还是调用 API，理解请求头都是至关重要的。本指南涵盖了最重要的请求头、使用场景，以及在 cURL、Python 和 JavaScript 中的实际代码示例。

什么是请求头？

每个 HTTP 请求都由三部分组成：

请求行 (Request line)：方法（GET、POST 等）和 URL。
请求头 (Headers)：关于请求的键值对元数据。
正文 (Body)：数据负载（用于 POST、PUT、PATCH 请求）。

以下是一个显示了这三部分的原始 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 请求头

当你的浏览器端 JavaScript 应用程序调用不同域名下的 API 时，跨源资源共享 (CORS) 请求头就变得非常重要。

预检请求头 (Preflight Request Headers)

当浏览器发送预检（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 和指定具体的 Origin（不能是 *）。

速率限制请求头 (Rate Limiting)

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（你想要接收什么）。除此之外，随着应用复杂度的增加，缓存头、CORS 头和速率限制头也会变得至关重要。

如果你正在构建需要调用 AI 媒体生成 API（用于图像、视频、数字人或音频）的应用，请关注 Hypereal AI。Hypereal 提供了统一的 API，具有简单的认证请求头以及按需付费的定价模式，让你轻松接入最前沿的生成式 AI 模型。

API 请求头：详尽指南 (2026)

什么是请求头？

每个 HTTP 请求都由三部分组成：

请求行 (Request line)：方法（GET、POST 等）和 URL。
请求头 (Headers)：关于请求的键值对元数据。
正文 (Body)：数据负载（用于 POST、PUT、PATCH 请求）。

以下是一个显示了这三部分的原始 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

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 请求头

当你的浏览器端 JavaScript 应用程序调用不同域名下的 API 时，跨源资源共享 (CORS) 请求头就变得非常重要。

预检请求头 (Preflight Request Headers)

当浏览器发送预检（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 和指定具体的 Origin（不能是 *）。

速率限制请求头 (Rate Limiting)

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`	请求追踪

开始使用 Hypereal 构建

API 请求头：详尽指南 (2026)

什么是请求头？

核心请求头

Content-Type

Authorization

Accept

User-Agent

缓存请求头

Cache-Control (请求)

If-None-Match / If-Modified-Since

CORS 请求头

预检请求头 (Preflight Request Headers)

常见 CORS 调试检查清单

速率限制请求头 (Rate Limiting)

请求 ID 与追踪请求头

在不同语言中设置请求头

Python (requests)

JavaScript (fetch)

JavaScript (axios)

cURL

快速参考表

总结

相关文章

HTTP Content-Type Header：完整指南 (2026)

HTTP DELETE 方法：完整指南 (2026)

GET vs POST：有什么区别？(2026)

立即开始构建

开始使用 Hypereal 构建

API 请求头：详尽指南 (2026)

什么是请求头？

核心请求头

Content-Type

Authorization

Accept

User-Agent

缓存请求头

Cache-Control (请求)

If-None-Match / If-Modified-Since

CORS 请求头

预检请求头 (Preflight Request Headers)

常见 CORS 调试检查清单

速率限制请求头 (Rate Limiting)

请求 ID 与追踪请求头

在不同语言中设置请求头

Python (requests)

JavaScript (fetch)

JavaScript (axios)

cURL

快速参考表

总结

相关文章

HTTP Content-Type Header：完整指南 (2026)

HTTP DELETE 方法：完整指南 (2026)

GET vs POST：有什么区别？(2026)

立即开始构建