Apify API Gateway · 快速开始

两步开始调用

1替换 Base URL将 https://api.apify.com 替换为上方 Gateway 地址。

2替换 Token使用分配给你的 Gateway Key，不要使用原始 Apify Token。

cURL

export APIFY_GATEWAY_KEY="<GATEWAY_KEY>"

curl --fail-with-body \
  -H "Authorization: Bearer ${APIFY_GATEWAY_KEY}" \
  "https://apify.351153.xyz/v2/users/me"

推荐使用 Authorization Header。虽然兼容 ?token=，但查询参数更容易被浏览器历史、代理或访问日志记录。

官方 SDK

SDK 的 Base URL 只填写域名，不要追加 /v2；客户端会自动拼接 API 版本路径。

JavaScript / TypeScript

import { ApifyClient } from 'apify-client';

const gatewayUrl = 'https://apify.351153.xyz';
const client = new ApifyClient({
  token: process.env.APIFY_GATEWAY_KEY,
  baseUrl: gatewayUrl,
  publicBaseUrl: gatewayUrl,
});

const user = await client.user().get();

Python

import os
from apify_client import ApifyClient

gateway_url = "https://apify.351153.xyz"
client = ApifyClient(
    token=os.environ["APIFY_GATEWAY_KEY"],
    api_url=gateway_url,
    api_public_url=gateway_url,
)

user = client.user().get()

不要在浏览器前端嵌入 Gateway Key。请只在服务器、Worker、CI 或其他可信后端环境中调用。

兼容范围与差异

透明转发/v2/* 的方法、路径、查询参数、请求体、二进制及流式响应会转发给 Apify。

账号池轮换无资源归属的请求可能由池中的不同账号处理，因此 /users/me 等账号级结果可能变化。

资源粘性Actor、Run、Dataset、KV Store、Request Queue、Task、Build、Webhook 和 Schedule 会继续路由到其所属账号。

安全 Failover仅无请求体的 GET、HEAD、OPTIONS 可自动切换账号；写请求不会自动重放。

额度接口说明：/v2/users/me/limits 和 /v2/users/me/usage/monthly 返回当前选中账号的数据，不代表整个账号池的汇总。

常见状态码

状态码	含义	建议
`401`	Gateway Key 无效或缺失	检查 Bearer Token，确认没有使用原始 Apify Token。
`429`	共享 Key 达到本地请求速率限制，或上游限流	遵循 `Retry-After`，对安全请求进行退避重试。
`503`	暂时没有可用账号，或资源所属账号不可用	稍后重试；不要盲目重放可能产生副作用的写请求。

每个代理响应都会包含 x-apify-gateway-request-id，排查问题时请保留该值。

只读检查

curl --fail-with-body "https://apify.351153.xyz/healthz"

健康检查无需 Token。管理接口不通过公网域名开放。