返回中文文档
认证
认证
API 认证
所有 API 请求都需要通过 API key 认证。每次请求都要把 key 放在x-api-key请求头中。
获取 API Key
Base URL
https://api.freeastroapi.com必需请求头
| 请求头 | 值 | 是否必需 |
|---|---|---|
| x-api-key | 你的 API key | 是 |
| Content-Type | application/json | 是（用于 POST） |
| Idempotency-Key | 客户端生成的唯一操作 key | 否（建议用于可计费 POST 重试） |
使用以下 header 安全重试: Idempotency-Key
经过认证且可能计费的占星 POST 支持 Idempotency-Key: <客户端生成的唯一操作 key>. 每个预期操作生成一个 key。只有在超时或网络失败后重试完全相同请求时，才复用同一个 key。
Node.js
const idempotencyKey = crypto.randomUUID();
await fetch("https://api.freeastroapi.com/api/v1/natal/calculate", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": process.env.FREE_ASTRO_API_KEY,
"Idempotency-Key": idempotencyKey
},
body: JSON.stringify(payload)
});Python
import uuid
idempotency_key = str(uuid.uuid4())
headers = {
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY",
"Idempotency-Key": idempotency_key
}认证示例
curl -X POST "https://api.freeastroapi.com/api/v1/natal/calculate" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"year": 1990, "month": 5, "day": 15, "hour": 10, "minute": 30, "city": "New York", "lat": 40.7128, "lng": -74.006}'安全最佳实践
- •不要在客户端代码中暴露 API key。 请从后端服务器发起 API 调用。
- •使用环境变量 来保存 API key，不要硬编码字符串。
- •轮换你的 API key 如果你怀疑 key 已泄露。
- •监控你的用量 在仪表盘中监控异常活动。
认证错误
| 状态 | 消息 | 说明 |
|---|---|---|
| 401 | Missing API key | 未提供 x-api-key header |
| 401 | Invalid API key | API key 不存在或已被撤销 |
| 429 | Rate limit exceeded | 你已超过当前套餐的请求限制 |
| 403 | Subscription required | 你的订阅已过期或未激活 |
速率限制
速率限制会根据订阅套餐不同而变化。每个响应都会包含以下 headers:
| Header | 说明 |
|---|---|
| X-RateLimit-Limit | 每个周期允许的总请求数 |
| X-RateLimit-Remaining | 当前周期剩余请求数 |
| X-RateLimit-Reset | 限制重置的 timestamp |