API Request Headers:完整指南 (2026)
关于 API 开发中 HTTP 请求头 (request headers) 你需要了解的一切
开始使用 Hypereal 构建
通过单个 API 访问 Kling、Flux、Sora、Veo 等。免费积分开始,扩展到数百万。
无需信用卡 • 10万+ 开发者 • 企业级服务
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 模型。
