返回 UTM Builder 工具页API

UTM Builder API

把一条或多条落地页链接批量加上统一 UTM 参数；可选 id 和 sourcePlatform 会输出为 utm_id 与 utm_source_platform。额度按成功生成的链接数量计算。

认证
在设置页创建 API key。完整密钥只显示一次，请复制到你的 Agent 或密钥管理器，之后页面只会显示脱敏后的 key。
Authorization: Bearer ecw_live_...
X-API-Key: ecw_live_...
额度与限速
API 调用有独立用量记录。成功和限额响应会提供 quota.remaining 与 rateLimit.remaining（以及对应的 X-* headers）；分钟限速按 UTC 整分钟窗口，并按每个 API key + 工具分别计数。超过每分钟上限会返回 429 rate_limited，请按 Retry-After 等待后再试。
X-Quota-Limit: 1000
X-Quota-Remaining: 997
X-RateLimit-Limit: 30
安全重试
网络超时或 Agent 自动重试时，使用同一个 Idempotency-Key。相同 key 与相同请求体会复用结果；换请求体会返回 idempotency_conflict，仍在处理时会返回 idempotency_in_progress。
Idempotency-Key: order-sync-2026-06-14-001
按 scope 授权
每个 API key 只选择实际需要的工具 scope，例如 tools:gtin:generate。scope 只限制工具，不会提升会员等级、额度或限速。
Scope: tools:gtin:generate
API key 安全
完整 API key 只显示一次。请保存到环境变量或密钥管理器，不要写入代码、URL、日志、截图或聊天记录；怀疑泄露时立即删除并重新创建。
ECOMWITH_API_KEY=ecw_live_...

错误与处理

错误响应使用 error.code 和 error.message。先按状态码和错误码处理，再决定是否等待或用同一个 Idempotency-Key 重试。

400invalid_request

修正 JSON body 后再发送，不要原样重复请求。

401authentication_required / invalid_api_key

检查 Authorization: Bearer 或 X-API-Key；不要把完整 key 写进错误日志。

403membership_required / insufficient_scope

检查当前套餐和 key 的 scope；scope 不能提升会员额度。

409idempotency_conflict / idempotency_in_progress

同一业务请求保持同一个 key；冲突先停止，处理中等待后用同 key 重试。

413payload_too_large

缩小请求体到当前套餐的 payload 限制以内，再重新发送。

429quota_exceeded / rate_limited / concurrency_limited

读取 X-Quota-*、X-RateLimit-* 和 Retry-After；额度为 0 时停止，限速或并发时等待。

错误响应结构

{"object":"tool_api.error","error":{"code":"invalid_request","message":"Request body must be a JSON object."}}

当前套餐额度

额度按 API key 所属用户的当前会员等级计算。分钟限制按每个 API key 对每个工具分别计算；超过上限会返回 429 rate_limited。请让 Agent 顺序发送请求，并以每次响应里的 quota 和 rateLimit 为准。

Basic

当前不包含 API 调用额度
每天额度
不可用
单次请求
不可用
每分钟
不可用
使用说明
如果接口返回 membership_required，请停止调用并检查当前账号套餐。

Pro

可调用
每天额度
1,000 条链接
单次请求
最多 100 条链接
每分钟
60 次请求
使用说明
urls 是批量链接列表；成功生成 10 条链接会消耗 10 个 link 额度。请在 quota.remaining 小于链接数时停止或拆分请求。

Max

可调用
每天额度
10,000 条链接
单次请求
最多 500 条链接
每分钟
200 次请求
使用说明
urls 是批量链接列表；成功生成 10 条链接会消耗 10 个 link 额度。请在 quota.remaining 小于链接数时停止或拆分请求。

请顺序调用

同一个 API key 对同一个工具一次只处理一个请求。如果返回 429 concurrency_limited，请等待上一个请求完成后，用同一个 Idempotency-Key 重试。

复制给你的 Agent
把这段话交给你的自动化 Agent，它会知道如何认证、请求、处理额度、限速和安全重试。
你是我的自动化 Agent。请使用 Ecomwith Tool API 调用 UTM Builder API，不要输出完整 API key。

认证:
- 从环境变量 ECOMWITH_API_KEY 读取密钥。
- 请求头使用 Authorization: Bearer <ECOMWITH_API_KEY>。

请求:
- Endpoint: POST https://ecomwith.com/api/v1/tools/utm-builder/build
- Body 示例: {"urls":["https://example.com/a","https://example.com/b"],"source":"meta","medium":"paid_social","campaign":"summer_launch","content":"adset_ad","term":"audience","id":"campaign-42","sourcePlatform":"meta_ads"}
- 成功生成 10 条链接会消耗 10 个 link 额度。invalid 数组里的链接不会扣量。

当前额度:
- Pro: 每天 1,000 条链接，单次最多 100 条链接，每分钟最多 60 次请求。
- Max: 每天 10,000 条链接，单次最多 500 条链接，每分钟最多 200 次请求。

调用规则:
- 顺序调用，不要并发调用同一个工具。
- 每个业务批次使用稳定 Idempotency-Key，例如 utm-campaign-2026-06-17-batch-1。
- 如果返回 concurrency_limited、rate_limited、quota_exceeded 或 idempotency_conflict，请按错误码停止或重试。

成功后请返回 links、invalid、quota.remaining 和 rateLimit.remaining。

示例请求

curl -X POST https://ecomwith.com/api/v1/tools/utm-builder/build \
  -H "Authorization: Bearer $ECOMWITH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: utm-batch-001" \
  -d '{"urls":["https://example.com/a","https://example.com/b"],"source":"meta","medium":"paid_social","campaign":"summer_launch","content":"adset_ad","term":"audience","id":"campaign-42","sourcePlatform":"meta_ads"}'