# 通过 HTTP 调用 API

Hub 上的每个 API 都通过同一个网关调用，使用相同的密钥和相同的响应头。

> 本页面适用于用自己的代码调用 API 的开发者。如果你是通过 AI 代理来用，这些内容都不需要你操心：参见 [连接 AI 代理（MCP）](https://zylalabs.com/zh/docs/mcp)。

## 发起第一次调用之前

1. 获取你的 [API 密钥](https://zylalabs.com/zh/docs/api-keys)。
2. 在 [目录](https://zylalabs.com/zh/api-marketplace) 中打开该 API 并订阅一个套餐（如果有免费试用，也可以直接开始试用）。对未订阅的 API 发起调用会返回 `401`。

## URL 格式

```text
https://zylalabs.com/api/{api_id}/{api_name}/{endpoint_id}/{endpoint_name}
```

API 页面会在 **Endpoints** 区域为你生成这个 URL，并附带每个端点的参数，以及 15 种编程语言（cURL、JavaScript、Node.js、Python、PHP、Java、Go、C# 等）的代码示例。请直接从那里复制，而不要自己手动拼接。

## 查询参数（GET）

```bash
curl 'https://zylalabs.com/api/{api_id}/{api_name}/{endpoint_id}/{endpoint_name}?email=john@example.com' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```javascript
const res = await fetch(
  'https://zylalabs.com/api/{api_id}/{api_name}/{endpoint_id}/{endpoint_name}?email=john@example.com',
  { headers: { Authorization: `Bearer ${process.env.ZYLA_API_KEY}` } }
);
const data = await res.json();
```

```python
import os, requests

r = requests.get(
    "https://zylalabs.com/api/{api_id}/{api_name}/{endpoint_id}/{endpoint_name}",
    params={"email": "john@example.com"},
    headers={"Authorization": f"Bearer {os.environ['ZYLA_API_KEY']}"},
)
print(r.status_code, r.json())
```

## JSON 请求体（POST）

使用端点页面上标明的方法。使用错误的方法会返回 `401`，并附带 `Invalid method`。

```bash
curl -X POST 'https://zylalabs.com/api/{api_id}/{api_name}/{endpoint_id}/{endpoint_name}' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"text": "Hello world"}'
```

## 响应头

每个成功的响应都会包含你的用量信息，方便你在自己这边做限流：

| 响应头 | 含义 |
|---|---|
| `X-Zyla-API-Calls-Monthly-Used` | 当前计费周期内该订阅已使用的调用次数 |
| `X-Zyla-API-Calls-Monthly-Remaining` | 本周期剩余的调用次数 |
| `X-Zyla-API-Calls-Monthly-Limit` | 你的套餐包含的调用次数 |
| `X-Zyla-RateLimit-Remaining` | 当前这一分钟内剩余的请求次数 |
| `X-Zyla-RateLimit-Reset-Seconds` | 距离每分钟限流窗口重置的剩余秒数 |

响应体就是提供商原样返回的内容。如果是网关自身产生的错误（未订阅、超出限制、未知端点），请参阅 [套餐、限制与错误](https://zylalabs.com/zh/docs/plans-and-limits)。


---
Source: https://zylalabs.com/zh/docs/calling-apis