zyla-api-hub-skill

Zyla API Hub 技能 — 将您的 OpenClaw AI 代理变成现实世界的操作员。通过 Zyla API Hub 中的 10,000 多个生产就绪的 API 为其提供支持 - 即时访问天气、财务、翻译、电子邮件验证、地理位置等。

# Zyla API Hub Skill

Turn your OpenClaw AI agent into a real-world operator.
Power it with 10,000+ production-ready APIs from Zyla API Hub — instant access to weather, finance, translation, email validation, geolocation, and more, all through one unified API key, pay-as-you-go pricing, and zero vendor lock-in.

## Setup

If `ZYLA_API_KEY` is not configured, guide the user:

1. Visit https://zylalabs.com/openclaw/connect to get an API key
2. Or run `/zyla connect` if the plugin is installed (opens browser automatically)
3. Add the key to `~/.openclaw/openclaw.json` under `skills.entries.zyla-api-hub-skill.apiKey`

Never ask the user to paste their API key in chat. Ask them to set it via the config and confirm when ready.

## Quick Start — Popular APIs

Use these directly without searching the catalog. Each includes the API ID, endpoint details, and parameters.

<!-- POPULAR_APIS_START -->
<!-- This section is auto-generated by: npx tsx scripts/generate-popular.ts -->
<!-- Run before publishing to update with the latest top 20 APIs by popularity -->

### Weather by Zip API (ID: 781)
- **Use when**: user asks about weather, temperature, forecast, climate, conditions by zip code
- **Category**: Weather & Environment
- **Call**: `npx tsx {baseDir}/scripts/zyla-api.ts call --api 781 --endpoint <endpoint_id> --params '{"zip":"10001"}'`

### Currency Conversion API (example)
- **Use when**: user asks about currency exchange, conversion rates, forex
- **Category**: Finance
- **Call**: `npx tsx {baseDir}/scripts/zyla-api.ts call --api <id> --endpoint <endpoint_id> --params '{"from":"USD","to":"EUR","amount":"100"}'`

### Email Validation API (example)
- **Use when**: user asks to validate, verify, or check an email address
- **Category**: Data Validation
- **Call**: `npx tsx {baseDir}/scripts/zyla-api.ts call --api <id> --endpoint <endpoint_id> --params '{"email":"test@example.com"}'`

> **Note**: Run `npx tsx {baseDir}/scripts/generate-popular.ts` to regenerate this section with real API IDs and endpoints from the live catalog.

<!-- POPULAR_APIS_END -->

## Discovering APIs

For APIs not listed above, search the catalog:

```bash
# Search by keyword
npx tsx {baseDir}/scripts/zyla-catalog.ts search "recipe"

# List APIs by category
npx tsx {baseDir}/scripts/zyla-catalog.ts list --category "Finance"

# Get endpoints for a specific API
npx tsx {baseDir}/scripts/zyla-catalog.ts endpoints --api 781
```

## Calling APIs

### Using the helper script (recommended)

```bash
# Basic call
npx tsx {baseDir}/scripts/zyla-api.ts call \
  --api <api_id> \
  --endpoint <endpoint_id> \
  --params '{"key":"value"}'

# Specify HTTP method (default: GET)
npx tsx {baseDir}/scripts/zyla-api.ts call \
  --api <api_id> \
  --endpoint <endpoint_id> \
  --method POST \
  --params '{"key":"value"}'

# Get info about an API
npx tsx {baseDir}/scripts/zyla-api.ts info --api <api_id>

# Check health and remaining quota
npx tsx {baseDir}/scripts/zyla-api.ts health
```

### Using curl (fallback)

```bash
curl -H "Authorization: Bearer $ZYLA_API_KEY" \
  "https://zylalabs.com/api/{api_id}/{api_slug}/{endpoint_id}/{endpoint_slug}?param=value"
```

**URL pattern**: `https://zylalabs.com/api/{api_id}/{api_name_slug}/{endpoint_id}/{endpoint_name_slug}`

- `api_id` and `endpoint_id` are numeric IDs (these do the actual routing)
- `api_name_slug` and `endpoint_name_slug` are URL-friendly names (for readability)

## Error Handling

- **401 Unauthorized**: API key is invalid or expired. Ask the user to run `/zyla connect` or visit https://zylalabs.com/openclaw/connect to get a new key.
- **403 Forbidden**: Subscription issue. The pay-as-you-go plan should handle this automatically. If it persists, ask the user to contact support.
- **429 Too Many Requests**: Rate limit exceeded. Check the `X-Zyla-RateLimit-Minute-Remaining` response header. Wait before retrying.
- **404 Not Found**: The API or endpoint does not exist. Verify the IDs using the catalog.
- **5xx Server Error**: Upstream API issue. Retry after a short delay (2-5 seconds).

## Rate Limit Headers

Every API response includes these headers:
- `X-Zyla-RateLimit-Minute-Limit`: Max requests per minute
- `X-Zyla-RateLimit-Minute-Remaining`: Remaining requests this minute
- `X-Zyla-API-Calls-Monthly-Used`: Total calls this billing cycle
- `X-Zyla-API-Calls-Monthly-Remaining`: Remaining calls this cycle

## Billing

- **Pay-as-you-go**: No monthly fee. Each API call is billed at the API's per-call rate.
- Billing happens at the end of each cycle via Stripe.
- Use the health endpoint to check current usage: `npx tsx {baseDir}/scripts/zyla-api.ts health`

---

## 中文说明

# Zyla API Hub 技能

将你的 OpenClaw AI 代理变成现实世界的操作员。
用 Zyla API Hub 提供的 10,000+ 个生产就绪的 API 为其赋能——即时访问天气、金融、翻译、邮箱校验、地理定位等等，全部通过一个统一的 API 密钥、按用量付费的定价，并且零供应商锁定。

## 设置

如果 `ZYLA_API_KEY` 未配置，请引导用户：

1. 访问 https://zylalabs.com/openclaw/connect 获取 API 密钥
2. 或者，如果已安装插件，运行 `/zyla connect`（会自动打开浏览器）
3. 将密钥添加到 `~/.openclaw/openclaw.json` 中的 `skills.entries.zyla-api-hub-skill.apiKey` 下

切勿要求用户在聊天中粘贴他们的 API 密钥。请让他们通过配置文件设置，并在就绪后确认。

## 快速上手 — 热门 API

直接使用这些 API，无需检索目录。每一项都包含 API ID、端点详情和参数。

<!-- POPULAR_APIS_START -->
<!-- This section is auto-generated by: npx tsx scripts/generate-popular.ts -->
<!-- Run before publishing to update with the latest top 20 APIs by popularity -->

### Weather by Zip API (ID: 781)
- **使用场景**：用户按邮编（zip code）询问天气、温度、预报、气候、状况
- **类别**：Weather & Environment
- **调用**：`npx tsx {baseDir}/scripts/zyla-api.ts call --api 781 --endpoint <endpoint_id> --params '{"zip":"10001"}'`

### Currency Conversion API (example)
- **使用场景**：用户询问货币兑换、汇率、外汇
- **类别**：Finance
- **调用**：`npx tsx {baseDir}/scripts/zyla-api.ts call --api <id> --endpoint <endpoint_id> --params '{"from":"USD","to":"EUR","amount":"100"}'`

### Email Validation API (example)
- **使用场景**：用户要求验证、校验或检查某个邮箱地址
- **类别**：Data Validation
- **调用**：`npx tsx {baseDir}/scripts/zyla-api.ts call --api <id> --endpoint <endpoint_id> --params '{"email":"test@example.com"}'`

> **注意**：运行 `npx tsx {baseDir}/scripts/generate-popular.ts` 以使用来自实时目录的真实 API ID 和端点重新生成此部分。

<!-- POPULAR_APIS_END -->

## 发现 API

对于上面未列出的 API，请检索目录：

```bash
# Search by keyword
npx tsx {baseDir}/scripts/zyla-catalog.ts search "recipe"

# List APIs by category
npx tsx {baseDir}/scripts/zyla-catalog.ts list --category "Finance"

# Get endpoints for a specific API
npx tsx {baseDir}/scripts/zyla-catalog.ts endpoints --api 781
```

## 调用 API

### 使用辅助脚本（推荐）

```bash
# Basic call
npx tsx {baseDir}/scripts/zyla-api.ts call \
  --api <api_id> \
  --endpoint <endpoint_id> \
  --params '{"key":"value"}'

# Specify HTTP method (default: GET)
npx tsx {baseDir}/scripts/zyla-api.ts call \
  --api <api_id> \
  --endpoint <endpoint_id> \
  --method POST \
  --params '{"key":"value"}'

# Get info about an API
npx tsx {baseDir}/scripts/zyla-api.ts info --api <api_id>

# Check health and remaining quota
npx tsx {baseDir}/scripts/zyla-api.ts health
```

### 使用 curl（备用方案）

```bash
curl -H "Authorization: Bearer $ZYLA_API_KEY" \
  "https://zylalabs.com/api/{api_id}/{api_slug}/{endpoint_id}/{endpoint_slug}?param=value"
```

**URL 模式**：`https://zylalabs.com/api/{api_id}/{api_name_slug}/{endpoint_id}/{endpoint_name_slug}`

- `api_id` 和 `endpoint_id` 是数字 ID（它们负责实际的路由）
- `api_name_slug` 和 `endpoint_name_slug` 是便于阅读的 URL 友好名称（用于可读性）

## 错误处理

- **401 Unauthorized**：API 密钥无效或已过期。请用户运行 `/zyla connect`，或访问 https://zylalabs.com/openclaw/connect 获取新密钥。
- **403 Forbidden**：订阅问题。按用量付费的套餐应能自动处理。如果持续出现，请用户联系支持。
- **429 Too Many Requests**：超出速率限制。检查 `X-Zyla-RateLimit-Minute-Remaining` 响应头。等待后再重试。
- **404 Not Found**：API 或端点不存在。使用目录核实 ID。
- **5xx Server Error**：上游 API 问题。短暂延迟（2-5 秒）后重试。

## 速率限制响应头

每个 API 响应都包含以下响应头：
- `X-Zyla-RateLimit-Minute-Limit`：每分钟最大请求数
- `X-Zyla-RateLimit-Minute-Remaining`：本分钟剩余请求数
- `X-Zyla-API-Calls-Monthly-Used`：本计费周期内的总调用数
- `X-Zyla-API-Calls-Monthly-Remaining`：本周期内剩余调用数

## 计费

- **按用量付费**：无月费。每次 API 调用按该 API 的单次调用费率计费。
- 计费在每个周期结束时通过 Stripe 进行。
- 使用 health 端点查看当前用量：`n