{
  "openapi": "3.1.0",
  "info": {
    "title": "RoamAI API",
    "version": "v1",
    "description": "RoamAI 的接口分两组：\n\n- **模型调用**：兼容 Anthropic Messages API 和 OpenAI Chat Completions API。Anthropic SDK、OpenAI SDK、Claude Code、Claude Desktop 都能直接用。\n- **管理**：查询用量和余额，创建、吊销 API Key。\n\n## 地址\n\n| 用途 | Base URL |\n| --- | --- |\n| 模型调用 | `https://cc-public.roamai.cloud:18443` |\n| 管理 | `https://roamai.cloud` |\n\n模型调用请用控制台「使用这个 Key」里给出的地址，那是你这个空间的地址。上表的地址所有空间都能用。\n\n## 认证\n\n所有接口都用控制台创建的 API Key（`rak1_` 开头），放在 `x-api-key` 请求头里，或者放在 `Authorization: Bearer` 里。\n\nAPI Key 能花你的余额，只在你自己的服务端使用，不要写进网页或 App。管理接口不接受其他网站页面在浏览器里发起的调用。\n\n## 错误\n\n错误的格式与 Anthropic API 相同：\n\n```json\n{\"type\": \"error\", \"error\": {\"type\": \"invalid_request_error\", \"message\": \"…\"}}\n```\n\n`/v1/chat/completions` 返回 OpenAI 格式的错误。message 里会写明原因。\n\n## 超时\n\n空间里请求多的时候，请求可能要排队等空位才开始。客户端超时请设成 10 分钟或更长（Anthropic 和 OpenAI 的 SDK 默认就是 10 分钟）。"
  },
  "servers": [
    {
      "url": "https://cc-public.roamai.cloud:18443",
      "description": "模型调用（以控制台给你这个空间的地址为准）"
    }
  ],
  "security": [
    {
      "ApiKey": []
    },
    {
      "Bearer": []
    }
  ],
  "tags": [
    {
      "name": "models",
      "x-displayName": "模型调用",
      "description": "兼容 Anthropic Messages API 和 OpenAI Chat Completions API。请求和返回的格式（包括流式事件）与官方文档相同，不同的地方写在各个接口下面。"
    },
    {
      "name": "usage",
      "x-displayName": "用量",
      "description": "服务器额度、余额和花费，可以接进你自己的看板和告警。"
    },
    {
      "name": "keys",
      "x-displayName": "Key 管理",
      "description": "在你自己的程序里创建、列出、吊销这个空间的 Key，比如给网关的每个用户各建一个，每个人可以单独限额、单独吊销。\n\n调用这几个接口，要用一个打开了「用 API 管理 Key」的 Key。这个开关在控制台这个 Key 的页面上，由 owner 或 admin 打开；只有 owner 或 admin 创建的 Key 才能打开。这个 Key 设了 IP 白名单的话，请求要从白名单里的地址发出。\n\n拿到管理用的 Key 的人可以创建不受限的 Key。请给它设 IP 白名单，只让你的服务器用。\n\n这样创建的 Key 和在控制台创建的一样：归创建管理 Key 的那个人，占这个空间 200 个 Key 的名额。"
    }
  ],
  "paths": {
    "/v1/messages": {
      "post": {
        "tags": [
          "models"
        ],
        "operationId": "createMessage",
        "summary": "创建消息",
        "description": "与 Anthropic Messages API 相同。`stream: true` 时返回 SSE 流。\n\n**支持：**文字、图片（base64）、你自己的工具和 `tool_choice`、网页搜索工具（`web_search_*`，不另外收费）、流式。\n\n**不支持：**\n- 文档（PDF 等）和图片链接。图片请用 base64。\n- 最后一条消息是 assistant（预填）。最后一条必须是 user。\n- `mcp_servers`。\n- 其他服务端工具（`bash_*`、`web_fetch_*`、`code_execution_*`）会被忽略。\n\n**参数：**`stop_sequences` 生效。`max_tokens` 用来预估这次请求的花费，不限制回答的长度。`temperature`、`top_p`、`top_k` 不生效。\n\nKey 的模型白名单和 effort 上限对这里生效：高于上限的 effort 按上限执行。",
        "externalDocs": {
          "url": "https://docs.claude.com/en/api/messages"
        },
        "servers": [
          {
            "url": "https://cc-public.roamai.cloud:18443",
            "description": "模型调用（以控制台给你这个空间的地址为准）"
          }
        ],
        "parameters": [
          {
            "name": "anthropic-version",
            "in": "header",
            "required": false,
            "description": "可选。为兼容 SDK 而接受。",
            "schema": {
              "type": "string",
              "example": "2023-06-01"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessageRequest"
              },
              "example": {
                "model": "claude-opus-5-5",
                "max_tokens": 1024,
                "messages": [
                  {
                    "role": "user",
                    "content": "Hello"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "消息。`stream: true` 时是 Anthropic 格式的 SSE 流。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                },
                "example": {
                  "id": "msg_roamai_8505248a3e24750ca2d8eda9",
                  "type": "message",
                  "role": "assistant",
                  "model": "claude-opus-5-5",
                  "content": [
                    {
                      "type": "text",
                      "text": "Hello! How can I help?"
                    }
                  ],
                  "stop_reason": "end_turn",
                  "stop_sequence": null,
                  "usage": {
                    "input_tokens": 12,
                    "output_tokens": 9,
                    "cache_read_input_tokens": 0,
                    "cache_creation_input_tokens": 0
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "请求格式不对或用了不支持的功能；或者余额用完了（请到控制台充值）。message 里写了是哪一种。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "invalid_request_error",
                    "message": "messages.0.content.0: content block type \"document\" is not supported by roamai api"
                  }
                }
              }
            }
          },
          "401": {
            "description": "API Key 不对、已吊销或已过期。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "authentication_error",
                    "message": "invalid api key (create one in the RoamAI console)"
                  }
                }
              }
            }
          },
          "403": {
            "description": "Key 已暂停或停用、请求的 IP 不在 Key 的白名单里，或者 Key 或空间不允许用这个模型。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "permission_error",
                    "message": "this API key cannot use model \"claude-haiku-4-5\"; it allows models starting with: claude-opus"
                  }
                }
              }
            }
          },
          "429": {
            "description": "这个 Key 同时在跑的请求太多，排队也没等到空位；Key 的某项花费上限（5 小时、1 天、7 天）用完了；或者同一个 IP 用错 Key 的次数太多。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "rate_limit_error",
                    "message": "this API key already has 3 requests running, its concurrency limit; waited 300s for one to finish. Try again when they finish, or send fewer requests at once."
                  }
                }
              }
            }
          },
          "503": {
            "description": "暂时没有服务器能接这个请求，请稍后重试。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "api_error",
                    "message": "No available accounts"
                  }
                }
              }
            }
          },
          "529": {
            "description": "排队等候期间服务器一直都忙，请稍后重试。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "overloaded_error",
                    "message": "waited 300s for a free slot; no free slot"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST https://cc-public.roamai.cloud:18443/v1/messages \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"claude-opus-5-5\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}'"
          },
          {
            "lang": "Python",
            "label": "Python",
            "source": "import anthropic\n\nclient = anthropic.Anthropic(base_url=\"https://cc-public.roamai.cloud:18443\", api_key=\"YOUR_API_KEY\")\nmessage = client.messages.create(\n    model=\"claude-opus-5-5\",\n    max_tokens=1024,\n    messages=[{\"role\": \"user\", \"content\": \"Hello\"}],\n)\nprint(message.content[0].text)"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "import Anthropic from \"@anthropic-ai/sdk\";\n\nconst client = new Anthropic({ baseURL: \"https://cc-public.roamai.cloud:18443\", apiKey: \"YOUR_API_KEY\" });\nconst message = await client.messages.create({\n  model: \"claude-opus-5-5\",\n  max_tokens: 1024,\n  messages: [{ role: \"user\", content: \"Hello\" }],\n});\nconsole.log(message.content[0].text);"
          }
        ]
      }
    },
    "/v1/messages/count_tokens": {
      "post": {
        "tags": [
          "models"
        ],
        "operationId": "countTokens",
        "summary": "统计 token（估算）",
        "description": "请求体与 `/v1/messages` 相同。返回的是**估算值**：中日韩字符每个算 1 个 token，其他文字每 3.5 个字符算 1 个，每张图片或每份文档算 1600。用来判断请求放不放得下够用，不用于计费。返回头带 `X-RoamAI-Token-Count: estimate`。不收费。",
        "servers": [
          {
            "url": "https://cc-public.roamai.cloud:18443",
            "description": "模型调用（以控制台给你这个空间的地址为准）"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessageRequest"
              },
              "example": {
                "model": "claude-opus-5-5",
                "max_tokens": 1024,
                "messages": [
                  {
                    "role": "user",
                    "content": "Hello"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "估算的 token 数。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenCount"
                },
                "example": {
                  "input_tokens": 12
                }
              }
            }
          },
          "400": {
            "description": "请求格式不对或用了不支持的功能；或者余额用完了（请到控制台充值）。message 里写了是哪一种。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "invalid_request_error",
                    "message": "messages.0.content.0: content block type \"document\" is not supported by roamai api"
                  }
                }
              }
            }
          },
          "401": {
            "description": "API Key 不对、已吊销或已过期。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "authentication_error",
                    "message": "invalid api key (create one in the RoamAI console)"
                  }
                }
              }
            }
          },
          "403": {
            "description": "Key 已暂停或停用、请求的 IP 不在 Key 的白名单里，或者 Key 或空间不允许用这个模型。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "permission_error",
                    "message": "this API key cannot use model \"claude-haiku-4-5\"; it allows models starting with: claude-opus"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST https://cc-public.roamai.cloud:18443/v1/messages/count_tokens \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"claude-opus-5-5\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}'"
          }
        ]
      }
    },
    "/v1/chat/completions": {
      "post": {
        "tags": [
          "models"
        ],
        "operationId": "createChatCompletion",
        "summary": "创建对话补全（兼容 OpenAI）",
        "description": "与 OpenAI Chat Completions API 相同，给只支持 OpenAI 格式的客户端用。模型名与 `/v1/messages` 相同。\n\n**不支持：**`tools` 和 `functions`；`n` 大于 1；图片链接（请用 base64 的 `data:` URL）。\n\n`stop` 生效。`max_tokens`（或 `max_completion_tokens`）用来预估花费，不限制回答的长度。`temperature`、`top_p` 不生效。\n\n流式时设 `stream_options.include_usage: true`，最后一块会带上 token 用量。",
        "externalDocs": {
          "url": "https://platform.openai.com/docs/api-reference/chat"
        },
        "servers": [
          {
            "url": "https://cc-public.roamai.cloud:18443",
            "description": "模型调用（以控制台给你这个空间的地址为准）"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatRequest"
              },
              "example": {
                "model": "claude-opus-5-5",
                "messages": [
                  {
                    "role": "user",
                    "content": "Hello"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "对话补全。`stream: true` 时是 OpenAI 格式的 SSE 流。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletion"
                },
                "example": {
                  "id": "chatcmpl-roamai-8505248a3e24750ca2d8eda9",
                  "object": "chat.completion",
                  "created": 1793350000,
                  "model": "claude-opus-5-5",
                  "choices": [
                    {
                      "index": 0,
                      "message": {
                        "role": "assistant",
                        "content": "Hello! How can I help?"
                      },
                      "finish_reason": "stop"
                    }
                  ],
                  "usage": {
                    "prompt_tokens": 12,
                    "completion_tokens": 9,
                    "total_tokens": 21,
                    "prompt_tokens_details": {
                      "cached_tokens": 0
                    }
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "请求格式不对或用了不支持的功能；或者余额用完了（请到控制台充值）。message 里写了是哪一种。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "invalid_request_error",
                    "message": "messages.0.content.0: content block type \"document\" is not supported by roamai api"
                  }
                }
              }
            }
          },
          "401": {
            "description": "API Key 不对、已吊销或已过期。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "authentication_error",
                    "message": "invalid api key (create one in the RoamAI console)"
                  }
                }
              }
            }
          },
          "403": {
            "description": "Key 已暂停或停用、请求的 IP 不在 Key 的白名单里，或者 Key 或空间不允许用这个模型。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "permission_error",
                    "message": "this API key cannot use model \"claude-haiku-4-5\"; it allows models starting with: claude-opus"
                  }
                }
              }
            }
          },
          "429": {
            "description": "这个 Key 同时在跑的请求太多，排队也没等到空位；Key 的某项花费上限（5 小时、1 天、7 天）用完了；或者同一个 IP 用错 Key 的次数太多。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "rate_limit_error",
                    "message": "this API key already has 3 requests running, its concurrency limit; waited 300s for one to finish. Try again when they finish, or send fewer requests at once."
                  }
                }
              }
            }
          },
          "503": {
            "description": "暂时没有服务器能接这个请求，请稍后重试。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "api_error",
                    "message": "No available accounts"
                  }
                }
              }
            }
          },
          "529": {
            "description": "排队等候期间服务器一直都忙，请稍后重试。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "overloaded_error",
                    "message": "waited 300s for a free slot; no free slot"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST https://cc-public.roamai.cloud:18443/v1/chat/completions \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\":\"claude-opus-5-5\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}'"
          },
          {
            "lang": "Python",
            "label": "Python",
            "source": "from openai import OpenAI\n\nclient = OpenAI(base_url=\"https://cc-public.roamai.cloud:18443/v1\", api_key=\"YOUR_API_KEY\")\ncompletion = client.chat.completions.create(\n    model=\"claude-opus-5-5\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello\"}],\n)\nprint(completion.choices[0].message.content)"
          }
        ]
      }
    },
    "/v1/models": {
      "get": {
        "tags": [
          "models"
        ],
        "operationId": "listModels",
        "summary": "列出模型",
        "description": "这个 Key 当前能用的模型，默认模型排在第一个。支持 1M token 上下文的模型只列一次，id 末尾带 `[1m]`。请求里写不带 `[1m]` 的 id、旧的模型 id 和别名也可以。",
        "servers": [
          {
            "url": "https://cc-public.roamai.cloud:18443",
            "description": "模型调用（以控制台给你这个空间的地址为准）"
          }
        ],
        "responses": {
          "200": {
            "description": "模型列表。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelList"
                },
                "example": {
                  "object": "list",
                  "data": [
                    {
                      "id": "claude-opus-5-5[1m]",
                      "type": "model",
                      "object": "model",
                      "display_name": "Opus 5.5",
                      "created_at": "2026-01-01T00:00:00Z",
                      "created": 0,
                      "owned_by": "roamai"
                    },
                    {
                      "id": "claude-sonnet-5-5",
                      "type": "model",
                      "object": "model",
                      "display_name": "Sonnet 5.5",
                      "created_at": "2026-01-01T00:00:00Z",
                      "created": 0,
                      "owned_by": "roamai"
                    }
                  ],
                  "has_more": false,
                  "first_id": null,
                  "last_id": null
                }
              }
            }
          },
          "401": {
            "description": "API Key 不对、已吊销或已过期。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "authentication_error",
                    "message": "invalid api key (create one in the RoamAI console)"
                  }
                }
              }
            }
          },
          "503": {
            "description": "暂时没有服务器能接这个请求，请稍后重试。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "api_error",
                    "message": "No available accounts"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl https://cc-public.roamai.cloud:18443/v1/models \\\n  -H \"x-api-key: YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v1/usage": {
      "get": {
        "tags": [
          "usage"
        ],
        "operationId": "getUsage",
        "summary": "查询用量和余额",
        "description": "服务器额度、余额和这个 Key 的花费。返回哪些内容取决于 Key 是谁创建的：\n\n| Key 的创建人 | 返回的内容 |\n| --- | --- |\n| owner 或 admin | 空间里所有服务器、套餐和余额、这个 Key 自己，以及空间里每个 Key 的用量（`keys`）。 |\n| 成员 | 这个 Key 能用的服务器、套餐和余额、这个 Key 自己。没有 `keys`。 |\n\n按创建人现在的角色算。已吊销的 Key、创建人已经离开空间的 Key 返回 401。暂停、停用、过期的 Key 照常返回，原因写在 `key.status` 里。\n\n服务器额度最快每 5 分钟变一次，每分钟拉一次就够了。时间都是 UTC 的 ISO 8601 格式，金额是余额里的美元。没有数据的字段为 `null`。",
        "servers": [
          {
            "url": "https://roamai.cloud",
            "description": "管理"
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "可选。日期（`YYYY-MM-DD`，从 UTC 零点起）或带时区的 ISO 时间。从这个时间起（含）的请求计入。",
            "schema": {
              "type": "string",
              "example": "2026-10-01"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "可选。写法同上。这个时间之前（不含）的请求计入。`from` 和 `to` 只影响 `usage` 里的合计，额度、余额和各时间窗口的花费总是当前的值。",
            "schema": {
              "type": "string",
              "example": "2026-11-01"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "用量和余额。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Usage"
                },
                "example": {
                  "object": "usage",
                  "scope": "workspace",
                  "generated_at": "2026-10-14T08:00:00.000Z",
                  "period": {
                    "from": "2026-10-13T00:00:00.000Z",
                    "to": null
                  },
                  "workspace": {
                    "plan": "vip_std",
                    "service": {
                      "active": true,
                      "until": "2026-11-02T00:00:00.000Z",
                      "renews": true
                    },
                    "balance": {
                      "usd": 187.42,
                      "enforced": true,
                      "refused": false
                    }
                  },
                  "servers": [
                    {
                      "name": "build-1",
                      "online": true,
                      "account": "ok",
                      "five_hour": {
                        "used_percent": 34,
                        "resets_at": "2026-10-14T10:13:00.000Z"
                      },
                      "seven_day": {
                        "used_percent": 41,
                        "resets_at": "2026-10-17T13:00:00.000Z"
                      },
                      "sampled_at": "2026-10-14T07:57:00.000Z",
                      "stale": false,
                      "api_reserve_percent": {
                        "five_hour": 50,
                        "seven_day": 80
                      },
                      "api_paused_until": null
                    },
                    {
                      "name": "build-2",
                      "online": true,
                      "account": "ok",
                      "five_hour": {
                        "used_percent": 52,
                        "resets_at": "2026-10-14T08:47:00.000Z"
                      },
                      "seven_day": {
                        "used_percent": 63,
                        "resets_at": "2026-10-19T10:00:00.000Z"
                      },
                      "sampled_at": "2026-10-14T07:56:00.000Z",
                      "stale": false,
                      "api_reserve_percent": {
                        "five_hour": 50,
                        "seven_day": 80
                      },
                      "api_paused_until": "2026-10-14T08:47:00.000Z"
                    }
                  ],
                  "key": {
                    "id": "5b0e2c1a-7d4f-4a8e-9c3b-1f2d3e4a5b6c",
                    "name": "ci-runner",
                    "prefix": "rak1_Qm7tK2",
                    "status": "active",
                    "created_at": "2026-09-02T03:15:00.000Z",
                    "last_used_at": "2026-10-14T07:58:41.000Z",
                    "expires_at": null,
                    "limits_usd": {
                      "total": null,
                      "5h": 20,
                      "1d": null,
                      "7d": null
                    },
                    "spend_usd": {
                      "total": 412.37,
                      "5h": 3.12,
                      "1d": 18.4,
                      "7d": 96.75
                    },
                    "exhausted": null,
                    "usage": {
                      "requests": 214,
                      "input_tokens": 2100000,
                      "output_tokens": 96000,
                      "cache_read_tokens": 28400000,
                      "cache_write_tokens": 1250000,
                      "web_searches": 3,
                      "cost_usd": 24.31,
                      "last_request_at": "2026-10-14T07:58:41.000Z",
                      "daily_tokens": {
                        "2026-10-13": 22415000,
                        "2026-10-14": 9431000
                      }
                    },
                    "allowed_models": null,
                    "max_effort": null,
                    "workspace_allowed_models": null,
                    "workspace_max_effort": null,
                    "recent_requests": [
                      {
                        "at": "2026-10-14T07:58:41.000Z",
                        "model": "claude-sonnet-5",
                        "input_tokens": 2140,
                        "output_tokens": 812,
                        "cache_read_tokens": 98200,
                        "cache_write_tokens": 1530,
                        "web_searches": 0,
                        "cost_usd": 0.0612
                      }
                    ]
                  },
                  "keys": [
                    {
                      "id": "5b0e2c1a-7d4f-4a8e-9c3b-1f2d3e4a5b6c",
                      "name": "ci-runner",
                      "prefix": "rak1_Qm7tK2",
                      "status": "active",
                      "created_at": "2026-09-02T03:15:00.000Z",
                      "last_used_at": "2026-10-14T07:58:41.000Z",
                      "expires_at": null,
                      "limits_usd": {
                        "total": null,
                        "5h": 20,
                        "1d": null,
                        "7d": null
                      },
                      "spend_usd": {
                        "total": 412.37,
                        "5h": 3.12,
                        "1d": 18.4,
                        "7d": 96.75
                      },
                      "exhausted": null,
                      "usage": {
                        "requests": 214,
                        "input_tokens": 2100000,
                        "output_tokens": 96000,
                        "cache_read_tokens": 28400000,
                        "cache_write_tokens": 1250000,
                        "web_searches": 3,
                        "cost_usd": 24.31,
                        "last_request_at": "2026-10-14T07:58:41.000Z",
                        "daily_tokens": {
                          "2026-10-13": 22415000,
                          "2026-10-14": 9431000
                        }
                      },
                      "creator_email": "lin@example.com",
                      "revoked_at": null,
                      "servers": []
                    },
                    {
                      "id": "c81f4b7e-2a90-4d3c-b6e5-8a7f9d0e1c2b",
                      "name": "design-laptop",
                      "prefix": "rak1_Vz3pN8",
                      "status": "active",
                      "created_at": "2026-09-20T09:40:00.000Z",
                      "last_used_at": "2026-10-14T07:41:05.000Z",
                      "expires_at": null,
                      "limits_usd": {
                        "total": null,
                        "5h": 5,
                        "1d": null,
                        "7d": null
                      },
                      "spend_usd": {
                        "total": 58.2,
                        "5h": 5,
                        "1d": 7.9,
                        "7d": 31.6
                      },
                      "exhausted": {
                        "window": "5h",
                        "limit_usd": 5,
                        "until": "2026-10-14T09:12:00.000Z"
                      },
                      "usage": {
                        "requests": 61,
                        "input_tokens": 640000,
                        "output_tokens": 31000,
                        "cache_read_tokens": 7900000,
                        "cache_write_tokens": 410000,
                        "web_searches": 0,
                        "cost_usd": 7.9,
                        "last_request_at": "2026-10-14T07:41:05.000Z",
                        "daily_tokens": {
                          "2026-10-13": 6120000,
                          "2026-10-14": 2861000
                        }
                      },
                      "creator_email": "chen@example.com",
                      "revoked_at": null,
                      "servers": [
                        "build-2"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`from` 或 `to` 不是日期或时间，或者 `from` 不早于 `to`。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "invalid_request_error",
                    "message": "from / to must be dates (YYYY-MM-DD) or ISO times, from before to"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Key 不对、已吊销，或者创建它的人已经离开这个空间。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "authentication_error",
                    "message": "invalid x-api-key"
                  }
                }
              }
            }
          },
          "429": {
            "description": "同一个 Key 一分钟内超过 30 次，或同一个 IP 一分钟内超过 60 次。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "rate_limit_error",
                    "message": "too many requests; poll at most once a minute"
                  }
                }
              }
            }
          },
          "500": {
            "description": "请求失败，一分钟后再试。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "api_error",
                    "message": "internal error"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl \"https://roamai.cloud/api/v1/usage?from=2026-10-01&to=2026-11-01\" \\\n  -H \"x-api-key: YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v1/keys": {
      "get": {
        "tags": [
          "keys"
        ],
        "operationId": "listKeys",
        "summary": "列出 Key",
        "description": "这个空间里没吊销的 Key，先创建的在前。`created_by_key` 是经这个接口创建它的那个管理 Key 的 id（`null` 表示在控制台创建的）。",
        "servers": [
          {
            "url": "https://roamai.cloud",
            "description": "管理"
          }
        ],
        "responses": {
          "200": {
            "description": "Key 列表。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeyList"
                },
                "example": {
                  "object": "list",
                  "data": [
                    {
                      "id": "8d3f0c2e-61b4-4f7a-a2d9-0e5c7b1f4a36",
                      "name": "alice@example.com",
                      "prefix": "rak1_Hs8wQ2a",
                      "status": "active",
                      "created_at": "2026-10-30T10:12:04.511284+00:00",
                      "last_used_at": null,
                      "expires_at": null,
                      "revoked_at": null,
                      "servers": [],
                      "limits_usd": {
                        "total": null,
                        "5h": null,
                        "1d": 20,
                        "7d": null
                      },
                      "allowed_models": null,
                      "allowed_ips": null,
                      "max_concurrency": 3,
                      "max_effort": null,
                      "can_manage_keys": false,
                      "created_by_key": "5b0e2c1a-7d4f-4a8e-9c3b-1f2d3e4a5b6c"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Key 不对、已吊销，或者创建它的人已经离开这个空间。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "authentication_error",
                    "message": "invalid x-api-key"
                  }
                }
              }
            }
          },
          "403": {
            "description": "这个 Key 不能管理 Key；或者它已暂停、停用、过期；或者请求的 IP 不在它的白名单里。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "permission_error",
                    "message": "this API key is not allowed to manage keys; an owner or admin can turn on \"Manage keys with the API\" on its page in the RoamAI console"
                  }
                }
              }
            }
          },
          "429": {
            "description": "同一个 Key 或同一个 IP 一分钟内超过 120 次。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "rate_limit_error",
                    "message": "too many requests; slow down"
                  }
                }
              }
            }
          },
          "500": {
            "description": "请求失败，一分钟后再试。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "api_error",
                    "message": "internal error"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl https://roamai.cloud/api/v1/keys \\\n  -H \"x-api-key: YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "tags": [
          "keys"
        ],
        "operationId": "createKey",
        "summary": "创建 Key",
        "description": "只有 `name` 必填。返回里的 `key` 是完整的 Key，**只出现这一次，请自己存好。**认不出的字段会被拒绝，免得拼错一个上限，建出来的 Key 却没有这项上限。",
        "servers": [
          {
            "url": "https://roamai.cloud",
            "description": "管理"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateKey"
              },
              "example": {
                "name": "alice@example.com",
                "max_concurrency": 3,
                "limits_usd": {
                  "1d": 20
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "新建的 Key，`key` 里是完整的 Key。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NewKey"
                },
                "example": {
                  "key": "rak1_Hs8wQ2aT…",
                  "id": "8d3f0c2e-61b4-4f7a-a2d9-0e5c7b1f4a36",
                  "name": "alice@example.com",
                  "prefix": "rak1_Hs8wQ2a",
                  "status": "active",
                  "created_at": "2026-10-30T10:12:04.511284+00:00",
                  "last_used_at": null,
                  "expires_at": null,
                  "revoked_at": null,
                  "servers": [],
                  "limits_usd": {
                    "total": null,
                    "5h": null,
                    "1d": 20,
                    "7d": null
                  },
                  "allowed_models": null,
                  "allowed_ips": null,
                  "max_concurrency": 3,
                  "max_effort": null,
                  "can_manage_keys": false,
                  "created_by_key": "5b0e2c1a-7d4f-4a8e-9c3b-1f2d3e4a5b6c"
                }
              }
            }
          },
          "400": {
            "description": "缺了字段或字段不对，message 里写了是哪一项。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "invalid_request_error",
                    "message": "unknown field: concurrency"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Key 不对、已吊销，或者创建它的人已经离开这个空间。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "authentication_error",
                    "message": "invalid x-api-key"
                  }
                }
              }
            }
          },
          "403": {
            "description": "这个 Key 不能管理 Key；或者它已暂停、停用、过期；或者请求的 IP 不在它的白名单里。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "permission_error",
                    "message": "this API key is not allowed to manage keys; an owner or admin can turn on \"Manage keys with the API\" on its page in the RoamAI console"
                  }
                }
              }
            }
          },
          "409": {
            "description": "这个空间没吊销的 Key 已经有 200 个。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "invalid_request_error",
                    "message": "the workspace already has 200 active API keys; revoke some first"
                  }
                }
              }
            }
          },
          "413": {
            "description": "请求体超过 16 KB。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "request_too_large",
                    "message": "request body too large"
                  }
                }
              }
            }
          },
          "429": {
            "description": "同一个 Key 或同一个 IP 一分钟内超过 120 次。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "rate_limit_error",
                    "message": "too many requests; slow down"
                  }
                }
              }
            }
          },
          "500": {
            "description": "请求失败，一分钟后再试。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "api_error",
                    "message": "internal error"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST https://roamai.cloud/api/v1/keys \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"name\":\"alice@example.com\",\"max_concurrency\":3,\"limits_usd\":{\"1d\":20}}'"
          }
        ]
      }
    },
    "/api/v1/keys/{id}": {
      "delete": {
        "tags": [
          "keys"
        ],
        "operationId": "revokeKey",
        "summary": "吊销 Key",
        "description": "吊销这个空间里的一个 Key（可以是管理 Key 自己）。大约一分钟内，带它的请求开始被拒绝。不能撤回。",
        "servers": [
          {
            "url": "https://roamai.cloud",
            "description": "管理"
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Key 的 `id`。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "吊销后的 Key。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Key"
                },
                "example": {
                  "id": "8d3f0c2e-61b4-4f7a-a2d9-0e5c7b1f4a36",
                  "name": "alice@example.com",
                  "prefix": "rak1_Hs8wQ2a",
                  "status": "revoked",
                  "created_at": "2026-10-30T10:12:04.511284+00:00",
                  "last_used_at": null,
                  "expires_at": null,
                  "revoked_at": "2026-10-31T02:00:00.000000+00:00",
                  "servers": [],
                  "limits_usd": {
                    "total": null,
                    "5h": null,
                    "1d": 20,
                    "7d": null
                  },
                  "allowed_models": null,
                  "allowed_ips": null,
                  "max_concurrency": 3,
                  "max_effort": null,
                  "can_manage_keys": false,
                  "created_by_key": "5b0e2c1a-7d4f-4a8e-9c3b-1f2d3e4a5b6c"
                }
              }
            }
          },
          "401": {
            "description": "Key 不对、已吊销，或者创建它的人已经离开这个空间。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "authentication_error",
                    "message": "invalid x-api-key"
                  }
                }
              }
            }
          },
          "403": {
            "description": "这个 Key 不能管理 Key；或者它已暂停、停用、过期；或者请求的 IP 不在它的白名单里。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "permission_error",
                    "message": "this API key is not allowed to manage keys; an owner or admin can turn on \"Manage keys with the API\" on its page in the RoamAI console"
                  }
                }
              }
            }
          },
          "404": {
            "description": "这个空间里没有这个 id 的、没吊销的 Key。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "not_found_error",
                    "message": "no active API key with this id in the workspace"
                  }
                }
              }
            }
          },
          "429": {
            "description": "同一个 Key 或同一个 IP 一分钟内超过 120 次。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "rate_limit_error",
                    "message": "too many requests; slow down"
                  }
                }
              }
            }
          },
          "500": {
            "description": "请求失败，一分钟后再试。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "type": "error",
                  "error": {
                    "type": "api_error",
                    "message": "internal error"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE https://roamai.cloud/api/v1/keys/8d3f0c2e-61b4-4f7a-a2d9-0e5c7b1f4a36 \\\n  -H \"x-api-key: YOUR_API_KEY\""
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "控制台创建的 API Key，放在 `x-api-key` 请求头里。"
      },
      "Bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "同一个 API Key，写成 `Authorization: Bearer rak1_…`。"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "const": "error",
            "description": "固定为 `error`。"
          },
          "error": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "description": "`invalid_request_error`、`authentication_error`、`permission_error`、`not_found_error`、`rate_limit_error`、`api_error` 或 `overloaded_error`。"
              },
              "message": {
                "type": "string",
                "description": "出错的原因。"
              }
            },
            "required": [
              "type",
              "message"
            ]
          }
        },
        "required": [
          "type",
          "error"
        ]
      },
      "MessageRequest": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string",
            "description": "`/v1/models` 里的模型 id，比如 `claude-opus-5-5`。"
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "必填（与 Anthropic API 相同）。用来预估花费，不限制回答的长度。"
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "对话内容。最后一条必须是 user。"
          },
          "system": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            ],
            "description": "系统提示：字符串或文字块。"
          },
          "stream": {
            "type": "boolean",
            "description": "`true` 时返回 SSE 流。"
          },
          "stop_sequences": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "遇到这些文字就结束回答。"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "你自己的工具（`name`、`description`、`input_schema`），以及网页搜索工具。"
          },
          "tool_choice": {
            "type": "object",
            "description": "`auto`、`any`、`tool`（带 `name`）或 `none`。"
          },
          "metadata": {
            "type": "object",
            "description": "同 Anthropic API。"
          }
        },
        "required": [
          "model",
          "max_tokens",
          "messages"
        ],
        "additionalProperties": true
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "消息 id。"
          },
          "type": {
            "type": "string",
            "const": "message",
            "description": "固定为 `message`。"
          },
          "role": {
            "type": "string",
            "const": "assistant",
            "description": "固定为 `assistant`。"
          },
          "model": {
            "type": "string",
            "description": "回答用的模型。"
          },
          "content": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "内容块：`text`、`tool_use`、网页搜索结果。"
          },
          "stop_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "`end_turn`、`max_tokens`、`stop_sequence` 或 `tool_use`。"
          },
          "stop_sequence": {
            "type": [
              "string",
              "null"
            ]
          },
          "usage": {
            "type": "object",
            "description": "token 用量：`input_tokens`、`output_tokens`、`cache_read_input_tokens`、`cache_creation_input_tokens`；用了网页搜索时另有 `server_tool_use.web_search_requests`。"
          }
        }
      },
      "TokenCount": {
        "type": "object",
        "properties": {
          "input_tokens": {
            "type": "integer",
            "description": "估算的输入 token 数。"
          }
        },
        "required": [
          "input_tokens"
        ]
      },
      "ChatRequest": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string",
            "description": "`/v1/models` 里的模型 id。"
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "`system`、`user`、`assistant` 消息。内容是字符串，或者文字和 `image_url` 片段。"
          },
          "max_tokens": {
            "type": "integer",
            "description": "用来预估花费，不限制回答的长度（也可以写 `max_completion_tokens`）。"
          },
          "stream": {
            "type": "boolean",
            "description": "`true` 时返回 SSE 流。"
          },
          "stream_options": {
            "type": "object",
            "properties": {
              "include_usage": {
                "type": "boolean"
              }
            },
            "description": "`{\"include_usage\": true}` 时，流的最后一块带上用量。"
          },
          "reasoning_effort": {
            "type": "string",
            "enum": [
              "minimal",
              "low",
              "medium",
              "high",
              "xhigh"
            ],
            "description": "`low`、`medium`、`high` 或 `xhigh`。"
          }
        },
        "required": [
          "model",
          "messages"
        ],
        "additionalProperties": true
      },
      "ChatCompletion": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "补全 id。"
          },
          "object": {
            "type": "string",
            "const": "chat.completion",
            "description": "固定为 `chat.completion`。"
          },
          "created": {
            "type": "integer"
          },
          "model": {
            "type": "string",
            "description": "回答用的模型。"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "一个选项，含 assistant 的 `message` 和 `finish_reason`。"
          },
          "usage": {
            "type": "object",
            "description": "`prompt_tokens`、`completion_tokens`、`total_tokens`，以及 `prompt_tokens_details.cached_tokens`。"
          }
        }
      },
      "Model": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "填进 `model` 的模型 id。"
          },
          "type": {
            "type": "string",
            "const": "model"
          },
          "object": {
            "type": "string",
            "const": "model"
          },
          "display_name": {
            "type": "string",
            "description": "显示名。"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "created": {
            "type": "integer"
          },
          "owned_by": {
            "type": "string"
          }
        }
      },
      "ModelList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "const": "list",
            "description": "固定为 `list`。"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Model"
            },
            "description": "模型。"
          },
          "has_more": {
            "type": "boolean"
          },
          "first_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_id": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Window": {
        "type": "object",
        "properties": {
          "used_percent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "已用百分比，0 到 100。"
          },
          "resets_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "重置时间。采样之后已经重置过的窗口显示 0，这一项为 `null`。"
          }
        }
      },
      "Server": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "服务器名。"
          },
          "online": {
            "type": "boolean",
            "description": "服务器此刻是否在线。"
          },
          "account": {
            "type": "string",
            "enum": [
              "ok",
              "banned",
              "login_invalid",
              "no_login",
              "unknown"
            ],
            "description": "Claude 账号状态：`ok`（正常）、`banned`（被封）、`login_invalid`（登录失效）、`no_login`（没有登录）或 `unknown`（还没检查到）。"
          },
          "five_hour": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Window"
              },
              {
                "type": "null"
              }
            ],
            "description": "订阅的 5 小时窗口。服务器还没有数据时为 `null`。"
          },
          "seven_day": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Window"
              },
              {
                "type": "null"
              }
            ],
            "description": "订阅的 7 天窗口。服务器还没有数据时为 `null`。"
          },
          "sampled_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "额度数据的采样时间。服务器在处理请求时随时更新，闲着时大约每小时更新一次；这里的数据比服务器最多晚 5 分钟。"
          },
          "stale": {
            "type": "boolean",
            "description": "数据超过 75 分钟没有更新时为 `true`。"
          },
          "api_reserve_percent": {
            "type": "object",
            "properties": {
              "five_hour": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "seven_day": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "description": "每个窗口留给订阅主人自己用的额度线。窗口用量到了这条线，这台服务器就不再接 API 请求，直到窗口重置。`null` 表示不留。"
          },
          "api_paused_until": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "因为用量到了 `api_reserve_percent` 而暂停接 API 请求时，恢复的时间。没有暂停时为 `null`。"
          }
        }
      },
      "Workspace": {
        "type": "object",
        "properties": {
          "plan": {
            "type": "string",
            "description": "`vip_std`、`vip_plus` 或 `none`（按用量付费）。"
          },
          "service": {
            "type": "object",
            "properties": {
              "active": {
                "type": "boolean",
                "description": "服务是否有效。"
              },
              "until": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "到期时间。自动续费的刷卡订阅给当期结束时间。没有到期时间时为 `null`。"
              },
              "renews": {
                "type": "boolean",
                "description": "刷卡订阅是否自动续费。"
              }
            }
          },
          "balance": {
            "type": "object",
            "properties": {
              "usd": {
                "type": "number",
                "description": "API 余额。"
              },
              "enforced": {
                "type": "boolean",
                "description": "余额用完后是否拒绝请求。"
              },
              "refused": {
                "type": "boolean",
                "description": "此刻是否因为余额用完在拒绝请求。"
              }
            }
          }
        }
      },
      "UsageKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Key 的 id。"
          },
          "name": {
            "type": "string",
            "description": "Key 的名字。"
          },
          "prefix": {
            "type": "string",
            "description": "Key 的开头几位。"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "paused",
              "locked",
              "expired",
              "disabled",
              "revoked"
            ],
            "description": "`active`（正常）、`paused`（已暂停）、`locked`（已停用，联系客服）、`expired`（已过期）、`disabled`（创建人已离开）或 `revoked`（已吊销）。"
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "创建时间。"
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "最后一次 API 请求的时间。"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "到期时间；`null` 表示不过期。"
          },
          "limits_usd": {
            "type": "object",
            "properties": {
              "total": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "总额。"
              },
              "5h": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 5 小时。"
              },
              "1d": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 24 小时。"
              },
              "7d": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 7 天。"
              }
            },
            "description": "花费上限：总额、5 小时、1 天、7 天。`null` 表示不限。"
          },
          "spend_usd": {
            "type": "object",
            "properties": {
              "total": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "总额。"
              },
              "5h": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 5 小时。"
              },
              "1d": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 24 小时。"
              },
              "7d": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 7 天。"
              }
            },
            "description": "同样四项的花费：累计、最近 5 小时、最近 24 小时、最近 7 天。"
          },
          "exhausted": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "window": {
                "type": "string",
                "enum": [
                  "total",
                  "5h",
                  "1d",
                  "7d"
                ]
              },
              "limit_usd": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "until": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            },
            "description": "某项花费上限用完时给出：`window`、`limit_usd` 和 `until`（恢复可用的时间，总额上限为 `null`）。"
          },
          "usage": {
            "type": "object",
            "properties": {
              "requests": {
                "type": "integer",
                "description": "请求数。"
              },
              "input_tokens": {
                "type": "integer",
                "description": "输入 token。"
              },
              "output_tokens": {
                "type": "integer",
                "description": "输出 token。"
              },
              "cache_read_tokens": {
                "type": "integer",
                "description": "缓存读取 token。"
              },
              "cache_write_tokens": {
                "type": "integer",
                "description": "缓存写入 token。"
              },
              "web_searches": {
                "type": "integer",
                "description": "网页搜索次数。"
              },
              "cost_usd": {
                "type": "number",
                "description": "花费。"
              },
              "last_request_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "时段内最后一个请求的时间。"
              },
              "daily_tokens": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                },
                "description": "按 UTC 日期的 token 数，只列有请求的日期。"
              }
            },
            "description": "时段内的合计。"
          },
          "allowed_models": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "这个 Key 的模型白名单（模型 id 开头）。`null` 表示不限。"
          },
          "max_effort": {
            "type": [
              "string",
              "null"
            ],
            "description": "这个 Key 的 effort 上限。`null` 表示不限。"
          },
          "workspace_allowed_models": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "整个空间的模型白名单。`null` 表示不限。"
          },
          "workspace_max_effort": {
            "type": [
              "string",
              "null"
            ],
            "description": "整个空间的 effort 上限。`null` 表示不限。"
          },
          "recent_requests": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "at": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time",
                  "description": "时间。"
                },
                "model": {
                  "type": "string",
                  "description": "模型。"
                },
                "input_tokens": {
                  "type": "integer"
                },
                "output_tokens": {
                  "type": "integer"
                },
                "cache_read_tokens": {
                  "type": "integer"
                },
                "cache_write_tokens": {
                  "type": "integer"
                },
                "web_searches": {
                  "type": "integer"
                },
                "cost_usd": {
                  "type": "number"
                }
              }
            },
            "description": "最近 20 个请求。"
          }
        }
      },
      "WorkspaceKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Key 的 id。"
          },
          "name": {
            "type": "string",
            "description": "Key 的名字。"
          },
          "prefix": {
            "type": "string",
            "description": "Key 的开头几位。"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "paused",
              "locked",
              "expired",
              "disabled",
              "revoked"
            ],
            "description": "`active`（正常）、`paused`（已暂停）、`locked`（已停用，联系客服）、`expired`（已过期）、`disabled`（创建人已离开）或 `revoked`（已吊销）。"
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "创建时间。"
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "最后一次 API 请求的时间。"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "到期时间；`null` 表示不过期。"
          },
          "limits_usd": {
            "type": "object",
            "properties": {
              "total": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "总额。"
              },
              "5h": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 5 小时。"
              },
              "1d": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 24 小时。"
              },
              "7d": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 7 天。"
              }
            },
            "description": "花费上限：总额、5 小时、1 天、7 天。`null` 表示不限。"
          },
          "spend_usd": {
            "type": "object",
            "properties": {
              "total": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "总额。"
              },
              "5h": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 5 小时。"
              },
              "1d": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 24 小时。"
              },
              "7d": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 7 天。"
              }
            },
            "description": "同样四项的花费：累计、最近 5 小时、最近 24 小时、最近 7 天。"
          },
          "exhausted": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "window": {
                "type": "string",
                "enum": [
                  "total",
                  "5h",
                  "1d",
                  "7d"
                ]
              },
              "limit_usd": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "until": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            },
            "description": "某项花费上限用完时给出：`window`、`limit_usd` 和 `until`（恢复可用的时间，总额上限为 `null`）。"
          },
          "usage": {
            "type": "object",
            "properties": {
              "requests": {
                "type": "integer",
                "description": "请求数。"
              },
              "input_tokens": {
                "type": "integer",
                "description": "输入 token。"
              },
              "output_tokens": {
                "type": "integer",
                "description": "输出 token。"
              },
              "cache_read_tokens": {
                "type": "integer",
                "description": "缓存读取 token。"
              },
              "cache_write_tokens": {
                "type": "integer",
                "description": "缓存写入 token。"
              },
              "web_searches": {
                "type": "integer",
                "description": "网页搜索次数。"
              },
              "cost_usd": {
                "type": "number",
                "description": "花费。"
              },
              "last_request_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "时段内最后一个请求的时间。"
              },
              "daily_tokens": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                },
                "description": "按 UTC 日期的 token 数，只列有请求的日期。"
              }
            },
            "description": "时段内的合计。"
          },
          "creator_email": {
            "type": [
              "string",
              "null"
            ],
            "description": "创建人的邮箱。"
          },
          "revoked_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "吊销时间。已吊销的 Key 只在时段内有用量时列出。"
          },
          "servers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "这个 Key 限定的服务器。空数组表示空间里所有服务器。"
          }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "const": "usage",
            "description": "固定为 `usage`。"
          },
          "scope": {
            "type": "string",
            "enum": [
              "workspace",
              "key"
            ],
            "description": "owner 或 admin 创建的 Key 为 `workspace`，其他为 `key`。"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time",
            "description": "这次返回的生成时间。"
          },
          "period": {
            "type": "object",
            "properties": {
              "from": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "to": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            },
            "description": "计算 `usage` 合计用的 `from` 和 `to`，没传时为 `null`。"
          },
          "workspace": {
            "$ref": "#/components/schemas/Workspace",
            "description": "套餐、服务期和余额。"
          },
          "servers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Server"
            },
            "description": "服务器和它们的订阅额度。"
          },
          "key": {
            "$ref": "#/components/schemas/UsageKey",
            "description": "发起这次请求的 Key。"
          },
          "keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WorkspaceKey"
            },
            "description": "空间里的每个 Key。只有 owner 或 admin 创建的 Key 才有。"
          }
        },
        "required": [
          "object",
          "scope",
          "generated_at",
          "workspace",
          "servers",
          "key"
        ]
      },
      "Key": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Key 的 id。"
          },
          "name": {
            "type": "string",
            "description": "Key 的名字。"
          },
          "prefix": {
            "type": "string",
            "description": "Key 的开头几位，用来认出是哪一个。"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "paused",
              "locked",
              "expired",
              "disabled",
              "revoked"
            ],
            "description": "`active`（正常）、`paused`（已暂停）、`locked`（已停用，联系客服）、`expired`（已过期）、`disabled`（创建人已离开）或 `revoked`（已吊销）。"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "创建时间。"
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "最后一次 API 请求的时间；`null` 表示没用过。"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "到期时间；`null` 表示不过期。"
          },
          "revoked_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "吊销时间；`null` 表示没吊销。"
          },
          "servers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "这个 Key 能用的服务器。空数组表示空间里所有服务器。"
          },
          "limits_usd": {
            "type": "object",
            "properties": {
              "total": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "总额。"
              },
              "5h": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 5 小时。"
              },
              "1d": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 24 小时。"
              },
              "7d": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "最近 7 天。"
              }
            },
            "description": "花费上限，单位美元：`total`、`5h`、`1d`、`7d`。`null` 表示不限。"
          },
          "allowed_models": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "能用的模型 id 开头，比如 `claude-opus`。`null` 表示不限。"
          },
          "allowed_ips": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "能从哪些 IP 地址或 CIDR 使用。`null` 表示不限。"
          },
          "max_concurrency": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 50,
            "description": "同时在跑的请求数。`null` 表示默认（3）。"
          },
          "max_effort": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "low",
              "medium",
              "high",
              "xhigh"
            ],
            "description": "effort 上限：`low`、`medium`、`high` 或 `xhigh`。`null` 表示不限。"
          },
          "can_manage_keys": {
            "type": "boolean",
            "description": "能不能调用这几个 Key 管理接口。"
          },
          "created_by_key": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "经这个接口创建它的那个管理 Key 的 id；`null` 表示在控制台创建的。"
          }
        }
      },
      "NewKey": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "description": "完整的 Key，只出现这一次。"
              }
            },
            "required": [
              "key"
            ]
          },
          {
            "$ref": "#/components/schemas/Key"
          }
        ]
      },
      "KeyList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "const": "list",
            "description": "固定为 `list`。"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Key"
            },
            "description": "Key 列表。"
          }
        }
      },
      "CreateKey": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "1 到 64 个字符，必填。"
          },
          "servers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "这个 Key 能用的服务器名字。为空或不填：空间里的服务器都能用。"
          },
          "limits_usd": {
            "type": "object",
            "properties": {
              "total": {
                "type": [
                  "number",
                  "null"
                ],
                "minimum": 0.01,
                "maximum": 1000000
              },
              "5h": {
                "type": [
                  "number",
                  "null"
                ],
                "minimum": 0.01,
                "maximum": 1000000
              },
              "1d": {
                "type": [
                  "number",
                  "null"
                ],
                "minimum": 0.01,
                "maximum": 1000000
              },
              "7d": {
                "type": [
                  "number",
                  "null"
                ],
                "minimum": 0.01,
                "maximum": 1000000
              }
            },
            "additionalProperties": false,
            "description": "花费上限，单位美元，每项 0.01 到 1000000。不填：不限。"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "日期（`YYYY-MM-DD`，那天 23:59 UTC 到期）或带时区的 ISO 时间。不填：不过期。"
          },
          "allowed_models": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 20,
            "description": "能用的模型 id 开头，比如 `claude-opus`（最多 20 个）。不填：不限。"
          },
          "allowed_ips": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 32,
            "description": "能从哪些 IP 地址或 CIDR 使用（最多 32 个）。不填：不限。"
          },
          "max_concurrency": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 50,
            "description": "同时在跑的请求数，1 到 50。不填：默认（3）。"
          },
          "max_effort": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "low",
              "medium",
              "high",
              "xhigh"
            ],
            "description": "effort 上限：`low`、`medium`、`high` 或 `xhigh`。不填：不限。"
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      }
    }
  }
}