API 参考

身份验证

所有 API 请求都需在 Authorization 请求头中以 Bearer token 形式传入有效的 API 密钥。

API 密钥以 ek_live_ 开头，可在控制台设置中生成。

bashcurl https://echloe.io/api/v1/audit \
  -H "Authorization: Bearer ek_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

基础 URL

https://echloe.io/api/v1

速率限制

触发速率限制时，API 返回 429 Too Many Requests。

运行 GEO 审计

对指定 URL 运行完整的 GEO（生成式引擎优化）审计，返回带分类明细、发现项与改进建议的详细评分。

请求体

示例

bashcurl -X POST https://echloe.io/api/v1/audit \
  -H "Authorization: Bearer ek_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

响应

json{
  "url": "https://example.com/",
  "score": 42,
  "categories": [
    {
      "name": "AI Citability",
      "score": 12,
      "maxScore": 25,
      "weight": 25,
      "details": "Average passage citability: 48/100..."
    }
  ],
  "findings": [
    {
      "severity": "critical",
      "category": "Schema & Structured Data",
      "message": "No JSON-LD structured data found."
    }
  ],
  "recommendations": [
    {
      "priority": 1,
      "title": "Fix: No JSON-LD structured data found",
      "description": "...",
      "impact": "high"
    }
  ],
  "crawledAt": "2026-04-02T12:00:00.000Z",
  "citability": { "averageScore": 48, "blockCount": 12, ... },
  "brandPresence": { "platforms": { ... }, "overallScore": 35 },
  "crawlerAccess": { "tier1Allowed": 5, "tier2Allowed": 7, ... },
  "llmsTxt": { "exists": false, ... },
  "schemaReport": { "typesFound": ["Organization"], ... }
}

生成内容

为某个产品生成 AI 内容（目前为博客文章）。内容会存入你的账户并在响应中返回。

请求体

示例

bashcurl -X POST https://echloe.io/api/v1/content \
  -H "Authorization: Bearer ek_live_..." \
  -H "Content-Type: application/json" \
  -d '{"productId": "abc123", "topic": "AI SEO best practices", "type": "blog_post"}'

响应

json{
  "id": "ctn_xyz789",
  "title": "AI SEO Best Practices for 2026",
  "content": "# AI SEO Best Practices for 2026\n\n..."
}

列出内容

返回你已生成内容的分页列表。

查询参数

示例

bashcurl "https://echloe.io/api/v1/content?limit=10" \
  -H "Authorization: Bearer ek_live_..."

响应

json{
  "items": [
    {
      "id": "...",
      "title": "AI SEO Best Practices",
      "type": "blog_post",
      "status": "draft",
      "tokenCount": 2048,
      "createdAt": "2026-04-01T10:00:00.000Z"
    }
  ],
  "limit": 10,
  "offset": 0
}

发现关键词

使用 AI 为某个产品发现最多 20 个新关键词。已发现的关键词会自动存储，后续调用不会重复返回。

请求体

示例

bashcurl -X POST https://echloe.io/api/v1/keywords \
  -H "Authorization: Bearer ek_live_..." \
  -H "Content-Type: application/json" \
  -d '{"productId": "abc123"}'

响应

json{
  "keywords": [
    {
      "id": "kw_001",
      "keyword": "ai content optimization",
      "intent": "informational",
      "difficulty": "medium",
      "source": "ai_discovered",
      "status": "active"
    }
  ],
  "count": 18
}

列出关键词

返回指定产品的全部关键词。

查询参数

示例

bashcurl "https://echloe.io/api/v1/keywords?productId=abc123" \
  -H "Authorization: Bearer ek_live_..."

Webhook

事件发生时，Echloe 可向你的服务器发送实时通知。请在控制台设置中配置 Webhook 端点。

事件

载荷格式

json{
  "event": "audit.completed",
  "timestamp": "2026-04-02T12:00:00.000Z",
  "data": {
    "url": "https://example.com",
    "score": 72,
    "auditId": "https://example.com/"
  }
}

请求头

签名校验

每个 Webhook 请求都带有 X-Echloe-Signature 请求头，其中包含用你的 Webhook 密钥对原始请求体签名得到的 HMAC-SHA256 值。

javascriptconst crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-echloe-signature'];
  const event = req.headers['x-echloe-event'];

  if (!verifyWebhook(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const payload = JSON.parse(req.rawBody);
  console.log('Received ' + event + ':', payload.data);
  res.status(200).send('OK');
});

错误处理

所有错误均以 JSON 返回：

json{
  "error": "Human-readable error message"
}