跳到正文
infrai文档
控制台

Discovery —— 会自我描述的 API

infrai 是 AI 应用的基础设施标准库,并且会自我描述:agent 无需读文档,可直接问 infrai「你能做什么」。Discovery API 返回完整能力集、每个能力的实时可用性、参数、错误码与当前价格——纯 HTTP,零安装。

能力索引

GET /v1/discovery 返回每个能力及其实时可用性(当前是否有健康的 vendor key)。公开,无需鉴权。

bash
# Enumerate every capability + its live availability:
curl https://api.infrai.cc/v1/discovery

每条包含能力 id、HTTP 方法与路径、一行摘要,以及当前可用状态——调用方在发请求前就知道该调什么、能否成功。

返回

json
{
  "version": "v1",
  "generated_at": "2026-06-03T12:00:00Z",
  "capabilities": [
    {
      "id": "email.send",
      "method": "POST",
      "path": "/v1/email/send",
      "available": true,
      "regions": ["western", "china"],
      "vendors": ["resend", "ses", "tencent"],
      "billing": {
        "is_billable": true,
        "free": false,
        "unit": "per_request",
        "price_usd": 0.0004,
        "currency": "USD",
        "new_account_trial_uses": 5000
      }
    }
    // … one object per capability.
    // NOTE: AI inference (chat/embeddings/images/audio/moderations/models) is
    // served OpenAI-API-compatible at /v1/chat/completions etc. — a parallel
    // standard surface, NOT listed in this discovery manifest.
  ]
}

单能力详情

GET /v1/discovery/{capability} 返回单个能力的完整契约。

bash
# Full detail for one capability — params, errors, runnable
# examples and the live billing block (free/paid, unit, current price):
curl https://api.infrai.cc/v1/discovery/email.send

参数、错误码(含可重试标志)、可运行的 curl / Python / JavaScript / TypeScript 示例,以及实时计费块——免费还是收费、计量单位与当前价格。OpenAPI 规范与本文档站都由同一份数据驱动。

返回

json
{
  "id": "email.send",
  "method": "POST",
  "path": "/v1/email/send",
  "available": true,
  "vendors": ["resend", "ses", "tencent"],
  "regions": ["western", "china"],
  "idempotent": true,
  "params": { "title": "EmailSendRequest", "required": ["to", "subject"], "...": "full JSON Schema" },
  "errors": ["RATE_LIMIT_VENDOR", "INSUFFICIENT_CREDIT", "VENDOR_DOWN", "..."],
  "examples": { "curl": "…", "python": "…", "javascript": "…", "typescript": "…" },
  "billing": {
    "is_billable": true,
    "free": false,
    "unit": "per_request",
    "price_usd": 0.0004,
    "currency": "USD",
    "approximate": false,
    "new_account_trial_uses": 5000
  }
}

实时价格,不写死

价格在运行时下发,绝不写死进客户端。详情响应含每能力的计费块,且对有余额的 key 会给出当前额度大约可调用多少次的提示——让 agent 在花钱前就能权衡成本。

机器描述符(.well-known)

面向工具与 AI 爬虫,提供静态、免鉴权的描述符:完整 OpenAPI 3.1 规范、MCP server 描述符,以及 llms.txt 索引。可直接喂给 Cursor、Claude、OpenAPI 客户端或搜索爬虫。

bash
# Static machine descriptors (no auth) for tools + AI crawlers:
curl https://api.infrai.cc/.well-known/openapi.json    # full OpenAPI 3.1
curl https://api.infrai.cc/.well-known/mcp.json         # MCP server descriptor
curl https://api.infrai.cc/llms.txt                     # AI-reading index

下一步