SkyQuest API 文档

SkyQuest REST API 允许开发者将 AI 可见度监测、内容生成和品牌追踪能力集成到自有应用中。所有 API 端点均通过 HTTPS 提供服务，请求和响应格式为 JSON。

一、认证方式

所有 API 请求均需通过 API Key 进行认证。请在请求头中包含 Authorization: Bearer YOUR_API_KEY。API Key 可在 SkyQuest 控制台「设置 > API 密钥」页面生成和管理。

curl -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx" \
     https://api.skyquest.cn/v1/brand/monitor

二、核心端点

POST /v1/brand/monitor

提交品牌监测任务。对目标品牌在指定 AI 引擎中的引用状态进行实时扫描，返回 BCR 评分、情感倾向和引用文本片段。

请求体：

{
  "brand_name": "SkyQuest",
  "keywords": ["AI visibility", "brand monitoring", "GEO tool"],
  "engines": ["chatgpt", "gemini", "perplexity", "claude"],
  "language": "en"
}

响应示例：

{
  "scan_id": "scan_9x8kF2aB",
  "brand_name": "SkyQuest",
  "status": "completed",
  "results": [
    {
      "engine": "chatgpt",
      "cited": true,
      "bcr_score": 0.82,
      "sentiment": "positive",
      "snippet": "SkyQuest is a leading AI visibility platform...",
      "source_url": "https://...",
      "timestamp": "2025-06-27T10:30:00Z"
    }
  ],
  "summary": {
    "total_engines": 4,
    "cited_engines": 3,
    "overall_bcr": 0.68,
    "avg_sentiment": "positive"
  }
}

POST /v1/content/generate

AI 驱动的内容生成。根据目标引擎和关键词，通过 RAG 增强检索生成高 AI 引用率的内容。支持指定内容类型、语调和长度偏好。

请求体：

{
  "brand_name": "SkyQuest",
  "topic": "What is Generative Engine Optimization",
  "target_engines": ["chatgpt", "perplexity"],
  "content_type": "article",
  "tone": "professional",
  "language": "en",
  "max_length": 1200
}

响应示例：

{
  "generation_id": "gen_7mNk3cDx",
  "status": "completed",
  "content": "Generative Engine Optimization (GEO)...",
  "metadata": {
    "schema_markup": "{...}",
    "recommended_keywords": ["GEO", "AI visibility", "brand citation"],
    "citation_score_estimate": 0.87
  }
}

POST /v1/report/export

生成并导出品牌 AI 可见度报告。支持 PDF 和 CSV 两种格式，可按时间范围、引擎、关键词等维度定制报告内容。

请求体：

{
  "brand_name": "SkyQuest",
  "date_range": {
    "start": "2025-06-01",
    "end": "2025-06-27"
  },
  "engines": ["chatgpt", "gemini", "perplexity"],
  "format": "pdf",
  "include_competitors": true
}

响应示例：

{
  "report_id": "rpt_v4Fh9gLw",
  "status": "processing",
  "estimated_completion": "2025-06-27T11:00:00Z",
  "download_url": null
}

三、速率限制

套餐	请求/分钟	请求/天	并发请求
Free	10	500	1
Pro	60	10,000	5
Business	300	100,000	20
Enterprise	自定义	自定义	自定义

超出速率限制时，API 返回 HTTP 429 状态码。响应头中包含 Retry-After 字段指示建议等待秒数。建议实现指数退避重试策略。

四、错误码参考

状态码	错误类型	说明
200	success	请求成功
400	bad_request	请求参数错误，请检查 JSON 格式和必填字段
401	unauthorized	API Key 缺失或无效
403	forbidden	无权限访问该资源，请检查套餐权限
404	not_found	请求的资源不存在
429	rate_limited	超出速率限制，请稍后重试
500	internal_error	服务器内部错误，我们会自动重试
503	service_unavailable	服务暂时不可用，通常维护中

所有错误响应均包含以下 JSON 结构：

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please retry after 30 seconds.",
    "retry_after": 30
  }
}