{"openapi":"3.1.0","info":{"title":"Eros Core API","description":"Core API MVP OpenAPI document for auth, user, project, and usage endpoints.","license":{"name":""},"version":"0.1.0"},"paths":{"/admin/users":{"get":{"tags":["user"],"operationId":"list_admin_users","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"返回管理端用户列表","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserListResponse"}}}},"401":{"description":"未登录或认证信息无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"当前用户不是管理员或账号已暂停","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"查询参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/admin/users/{id}":{"get":{"tags":["user"],"operationId":"get_admin_user","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"返回用户详情","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserDetailResponse"}}}},"401":{"description":"未登录或认证信息无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"当前用户不是管理员或账号已暂停","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"目标用户不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"路径参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/admin/users/{id}/activate":{"post":{"tags":["user"],"operationId":"activate_user","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"激活用户成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserActionResponse"}}}},"401":{"description":"未登录或认证信息无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"当前用户不是管理员或目标用户缺少待审核申请","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"目标用户不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"当前用户状态不允许激活","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"路径参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/admin/users/{id}/reject":{"post":{"tags":["user"],"operationId":"reject_user","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"拒绝用户申请成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserActionResponse"}}}},"401":{"description":"未登录或认证信息无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"当前用户不是管理员或目标用户缺少待审核申请","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"目标用户不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"当前用户状态不允许拒绝","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"路径参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/admin/users/{id}/restore":{"post":{"tags":["user"],"operationId":"restore_user","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"恢复用户成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserActionResponse"}}}},"401":{"description":"未登录或认证信息无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"当前用户不是管理员","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"目标用户不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"当前用户状态不允许恢复","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"路径参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/admin/users/{id}/suspend":{"post":{"tags":["user"],"operationId":"suspend_user","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"暂停用户成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserActionResponse"}}}},"401":{"description":"未登录或认证信息无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"当前用户不是管理员","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"目标用户不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"当前用户状态不允许暂停","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"路径参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/admin/users/{id}/usage/records":{"get":{"tags":["usage"],"operationId":"get_admin_usage_records","parameters":[{"name":"Authorization","in":"header","description":"Bearer access token，格式为 `Bearer <token>`。","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"Target user id","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"start_date","in":"query","required":false,"schema":{"type":"string"},"example":"2026-04-21"},{"name":"end_date","in":"query","required":false,"schema":{"type":"string"},"example":"2026-04-21"},{"name":"capability","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Capability"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1}},{"name":"format","in":"query","required":true,"schema":{"$ref":"#/components/schemas/OutputFormat"}}],"responses":{"200":{"description":"Target user usage records in JSON or CSV format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageRecordsPayloadResponse"}},"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid path or query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/admin/users/{id}/usage/summary":{"get":{"tags":["usage"],"operationId":"get_admin_usage_summary","parameters":[{"name":"Authorization","in":"header","description":"Bearer access token，格式为 `Bearer <token>`。","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"Target user id","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"start_date","in":"query","required":false,"schema":{"type":"string"},"example":"2026-04-21"},{"name":"end_date","in":"query","required":false,"schema":{"type":"string"},"example":"2026-04-21"},{"name":"format","in":"query","required":true,"schema":{"$ref":"#/components/schemas/OutputFormat"}}],"responses":{"200":{"description":"Target user usage summary in JSON or CSV format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSummaryPayloadResponse"}},"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid path or query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/auth/google":{"get":{"tags":["auth"],"operationId":"google_login","parameters":[{"name":"redirect_to","in":"query","description":"登录成功后的前端回跳地址。支持相对路径，或与允许前端 origin 相同的绝对 URL。","required":false,"schema":{"type":"string"}}],"responses":{"302":{"description":"重定向到 Google OAuth 授权地址，并写入 OAuth state Cookie。","headers":{"Location":{"schema":{"type":"string"},"description":"Google OAuth 授权地址。"},"Set-Cookie":{"schema":{"type":"string"},"description":"浏览器 OAuth state Cookie。"}}},"400":{"description":"redirect_to 不合法或不在允许的前端 origin 内。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorEnvelope"}}}},"500":{"description":"OAuth 配置无效或响应头构造失败。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorEnvelope"}}}}}}},"/auth/google/callback":{"get":{"tags":["auth"],"operationId":"google_callback","parameters":[{"name":"code","in":"query","description":"Google OAuth 授权码。","required":true,"schema":{"type":"string"}},{"name":"state","in":"query","description":"前一步签发的 OAuth state token。","required":true,"schema":{"type":"string"}}],"responses":{"302":{"description":"完成 Google OAuth 登录，清理临时 Cookie，并跳转到前端 Bearer token callback 页面。","headers":{"Location":{"schema":{"type":"string"},"description":"前端 callback 页面地址，Bearer token 放在 URL fragment 中。"},"Set-Cookie":{"schema":{"type":"string"},"description":"清理旧认证 Cookie 与 OAuth state Cookie 的响应头。"}}},"401":{"description":"OAuth state 校验失败，或 Google OAuth 认证未通过。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorEnvelope"}}}},"409":{"description":"Google 账号与现有用户记录冲突。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorEnvelope"}}}},"500":{"description":"Google OAuth 交换、用户资料解析或响应头构造失败。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorEnvelope"}}}}}}},"/bk/auth/verify":{"get":{"tags":["project"],"operationId":"verify_api_key","parameters":[{"name":"x-internal-token","in":"header","description":"Required internal gateway token.","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"API key supplied directly in a header.","required":false,"schema":{"type":["string","null"]}},{"name":"Authorization","in":"header","description":"Bearer token form of the API key.","required":false,"schema":{"type":["string","null"]}},{"name":"api_key","in":"query","description":"Fallback query parameter for the API key.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key verified successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyApiKeyResponse"}}}},"401":{"description":"The internal token is invalid, or the API key is invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The tenant or API key owner is not allowed to use the API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/bk/usage":{"post":{"tags":["usage"],"operationId":"post_internal_usage","parameters":[{"name":"X-Internal-Token","in":"header","description":"Internal service token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalUsageWriteRequestPayload"}}},"required":true},"responses":{"200":{"description":"Usage report accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportUsageReceiptResponse"}}}},"401":{"description":"Missing or invalid internal token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/bk/users/{id}/admin":{"post":{"tags":["user"],"operationId":"grant_internal_admin","parameters":[{"name":"X-Internal-Token","in":"header","description":"Internal service token","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"将目标用户设置为 admin 成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserDetailResponse"}}}},"401":{"description":"缺少或无效的 internal token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"目标用户不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"路径参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"tags":["user"],"operationId":"revoke_internal_admin","parameters":[{"name":"X-Internal-Token","in":"header","description":"Internal service token","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"将目标用户移出 admin 成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserDetailResponse"}}}},"401":{"description":"缺少或无效的 internal token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"目标用户不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"路径参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/auth/logout":{"post":{"tags":["auth"],"operationId":"logout","responses":{"204":{"description":"清理遗留浏览器认证 Cookie；Bearer token 由前端自行删除。","headers":{"Set-Cookie":{"schema":{"type":"string"},"description":"清空认证 Cookie 的响应头。"}}},"500":{"description":"响应头构造失败。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorEnvelope"}}}}}}},"/v1/me":{"get":{"tags":["user"],"operationId":"get_me","responses":{"200":{"description":"返回当前登录用户信息","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"未登录或认证信息无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"用户不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/onboarding":{"post":{"tags":["user"],"operationId":"post_onboarding","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingRequest"}}},"required":true},"responses":{"200":{"description":"提交或重新提交入驻申请成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingResponse"}}}},"401":{"description":"未登录或认证信息无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"账号已暂停或已有待审核申请","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"当前用户状态不允许提交申请","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"请求参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"服务器内部错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/projects":{"get":{"tags":["project"],"operationId":"list_projects","responses":{"200":{"description":"List active projects for the current tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListProjectsResponse"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The current user or tenant cannot access project APIs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"An active tenant membership is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["project"],"operationId":"create_project","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectRequest"}}},"required":true},"responses":{"201":{"description":"Project created and a one-time API key is returned.","headers":{"Location":{"schema":{"type":"string"},"description":"Location of the created project resource."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectResponse"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The current user or tenant cannot access project APIs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The project name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"The request payload is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/projects/{id}":{"delete":{"tags":["project"],"operationId":"delete_project","parameters":[{"name":"id","in":"path","description":"Project ID.","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"Project deleted and any active keys revoked."},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The current user or tenant cannot access project APIs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The project was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"The path parameter is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/projects/{id}/api-keys":{"post":{"tags":["project"],"operationId":"create_project_key","parameters":[{"name":"id","in":"path","description":"Project ID.","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"201":{"description":"Project API key created and returned once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectKeyResponse"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The current user or tenant cannot access project APIs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The project was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"The path parameter is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/projects/{id}/api-keys/{api_key_id}":{"delete":{"tags":["project"],"operationId":"delete_project_key","parameters":[{"name":"id","in":"path","description":"Project ID.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"api_key_id","in":"path","description":"API key ID.","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"Project API key revoked."},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The current user or tenant cannot access project APIs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The project or API key was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A path parameter is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/usage/records":{"get":{"tags":["usage"],"operationId":"get_usage_records","parameters":[{"name":"Authorization","in":"header","description":"Bearer access token，格式为 `Bearer <token>`。","required":true,"schema":{"type":"string"}},{"name":"start_date","in":"query","required":false,"schema":{"type":"string"},"example":"2026-04-21"},{"name":"end_date","in":"query","required":false,"schema":{"type":"string"},"example":"2026-04-21"},{"name":"capability","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Capability"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1}},{"name":"format","in":"query","required":true,"schema":{"$ref":"#/components/schemas/OutputFormat"}}],"responses":{"200":{"description":"Usage records in JSON or CSV format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageRecordsPayloadResponse"}},"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The current account cannot access usage data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/usage/summary":{"get":{"tags":["usage"],"operationId":"get_usage_summary","parameters":[{"name":"Authorization","in":"header","description":"Bearer access token，格式为 `Bearer <token>`。","required":true,"schema":{"type":"string"}},{"name":"start_date","in":"query","required":false,"schema":{"type":"string"},"example":"2026-04-21"},{"name":"end_date","in":"query","required":false,"schema":{"type":"string"},"example":"2026-04-21"},{"name":"format","in":"query","required":true,"schema":{"$ref":"#/components/schemas/OutputFormat"}}],"responses":{"200":{"description":"Usage summary in JSON or CSV format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSummaryPayloadResponse"}},"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The current account cannot access usage data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}},"components":{"schemas":{"AdminUserActionResponse":{"type":"object","required":["id","state"],"properties":{"application_status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ApplicationStatus"}]},"id":{"$ref":"#/components/schemas/i64"},"state":{"$ref":"#/components/schemas/UserState"},"tenant":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TenantSummary"}]}}},"AdminUserDetailResponse":{"type":"object","required":["id","email","name","state","is_admin","created_at"],"properties":{"application":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ApplicationSnapshot"}]},"created_at":{"$ref":"#/components/schemas/String"},"email":{"type":"string"},"id":{"$ref":"#/components/schemas/i64"},"is_admin":{"type":"boolean"},"last_login_at":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/String"}]},"member_since":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/String"}]},"name":{"type":"string"},"state":{"$ref":"#/components/schemas/UserState"},"tenant":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TenantSummary"}]}}},"AdminUserListItem":{"type":"object","required":["id","name","email","state"],"properties":{"application_status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ApplicationStatus"}]},"application_submitted_at":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/String"}]},"company_name":{"type":["string","null"]},"email":{"type":"string"},"id":{"$ref":"#/components/schemas/i64"},"member_since":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/String"}]},"name":{"type":"string"},"state":{"$ref":"#/components/schemas/UserState"}}},"AdminUserListResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserListItem"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}}},"ApiKeyStatus":{"type":"string","enum":["active","revoked"]},"ApplicationSnapshot":{"type":"object","required":["id","application_status","company_name","contact_name","work_email","company_size","use_case","submitted_at"],"properties":{"application_status":{"$ref":"#/components/schemas/ApplicationStatus"},"billing_address":{"type":["string","null"]},"company_name":{"type":"string"},"company_size":{"type":"string"},"company_website":{"type":["string","null"]},"contact_name":{"type":"string"},"contact_phone":{"type":["string","null"]},"id":{"$ref":"#/components/schemas/i64"},"reviewed_at":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/String"}]},"reviewed_by":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/i64"}]},"submitted_at":{"$ref":"#/components/schemas/String"},"tax_id":{"type":["string","null"]},"use_case":{"type":"string"},"work_email":{"type":"string"}}},"ApplicationStatus":{"type":"string","enum":["submitted","approved","rejected"]},"AuthErrorBody":{"type":"object","required":["code","message"],"properties":{"code":{"$ref":"#/components/schemas/AuthErrorCode"},"message":{"type":"string"}}},"AuthErrorCode":{"type":"string","enum":["unauthorized","forbidden","account_suspended","application_required","application_rejected","validation_error","conflict","internal_error"]},"AuthErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/AuthErrorBody"}}},"Capability":{"type":"string","enum":["subtitle","translation","compliance","image_to_video","video_generation_sd","video_generation_hd"]},"CreateProjectKeyResponse":{"type":"object","required":["project_id","api_key_id","key","key_prefix","key_suffix","created_at"],"properties":{"api_key_id":{"type":"integer","format":"int64"},"created_at":{"type":"string"},"key":{"type":"string"},"key_prefix":{"type":"string"},"key_suffix":{"type":"string"},"project_id":{"type":"integer","format":"int64"}}},"CreateProjectRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}},"CreateProjectResponse":{"type":"object","required":["project_id","api_key_id","name","key","key_prefix","key_suffix","created_at"],"properties":{"api_key_id":{"type":"integer","format":"int64"},"created_at":{"type":"string"},"key":{"type":"string"},"key_prefix":{"type":"string"},"key_suffix":{"type":"string"},"name":{"type":"string"},"project_id":{"type":"integer","format":"int64"}}},"ErrorBody":{"type":"object","required":["code","message"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"}}},"ErrorCode":{"type":"string","enum":["unauthorized","forbidden","account_suspended","application_required","application_pending","application_rejected","invalid_api_key","resource_not_found","conflict","validation_error","internal_error"]},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}}},"InternalUsageWriteRequestPayload":{"type":"object","required":["tenant_id","user_id","project_id","api_key_id","capability","quantity","unit","request_id"],"properties":{"api_key_id":{"type":"integer","format":"int64","example":4},"capability":{"$ref":"#/components/schemas/Capability"},"event_id":{"type":["integer","null"],"format":"int64","example":1},"project_id":{"type":"integer","format":"int64","example":3},"quantity":{"type":"string","example":"1"},"request_id":{"type":"string","example":"req_20260421_0001"},"tenant_id":{"type":"integer","format":"int64","example":1},"unit":{"$ref":"#/components/schemas/UsageUnit"},"user_id":{"type":"integer","format":"int64","example":2}}},"ListProjectsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectListItemResponse"}}}},"MeResponse":{"type":"object","required":["id","email","name","state","is_admin"],"properties":{"application":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ApplicationSnapshot"}]},"application_status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ApplicationStatus"}]},"email":{"type":"string"},"id":{"$ref":"#/components/schemas/i64"},"is_admin":{"type":"boolean"},"name":{"type":"string"},"state":{"$ref":"#/components/schemas/UserState"},"tenant":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TenantSummary"}]}}},"OnboardingRequest":{"type":"object","required":["company_name","contact_name","work_email","company_size","use_case"],"properties":{"billing_address":{"type":["string","null"]},"company_name":{"type":"string"},"company_size":{"type":"string"},"company_website":{"type":["string","null"]},"contact_name":{"type":"string"},"contact_phone":{"type":["string","null"]},"tax_id":{"type":["string","null"]},"use_case":{"type":"string"},"work_email":{"type":"string"}}},"OnboardingResponse":{"type":"object","required":["id","state","application_status","submitted_at"],"properties":{"application_status":{"$ref":"#/components/schemas/ApplicationStatus"},"id":{"$ref":"#/components/schemas/i64"},"state":{"$ref":"#/components/schemas/UserState"},"submitted_at":{"$ref":"#/components/schemas/String"}}},"OutputFormat":{"type":"string","enum":["json","csv"]},"PaginationMetadata":{"type":"object","required":["total","page","per_page","has_more"],"properties":{"has_more":{"type":"boolean"},"page":{"type":"integer","format":"int64"},"per_page":{"type":"integer","format":"int64"},"total":{"type":"integer","minimum":0}}},"ProjectApiKeyResponse":{"type":"object","required":["api_key_id","key_prefix","key_suffix","created_at"],"properties":{"api_key_id":{"type":"integer","format":"int64"},"created_at":{"type":"string"},"key_prefix":{"type":"string"},"key_suffix":{"type":"string"},"last_used_at":{"type":["string","null"]}}},"ProjectListItemResponse":{"type":"object","required":["project_id","name","api_keys"],"properties":{"api_keys":{"type":"array","items":{"$ref":"#/components/schemas/ProjectApiKeyResponse"}},"name":{"type":"string"},"project_id":{"type":"integer","format":"int64"}}},"ProjectStatus":{"type":"string","enum":["active","deleted"]},"ReportUsageReceiptResponse":{"type":"object","required":["id","project_id","request_id","created","created_at"],"properties":{"created":{"type":"boolean"},"created_at":{"type":"string","example":"2026-04-21T12:00:00Z"},"id":{"type":"integer","format":"int64","example":1},"project_id":{"type":"integer","format":"int64","example":3},"request_id":{"type":"string","example":"req_20260421_0001"}}},"String":{"type":"string"},"TenantStatus":{"type":"string","enum":["active","suspended"]},"TenantSummary":{"type":"object","required":["id","name","status"],"properties":{"id":{"$ref":"#/components/schemas/i64"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/TenantStatus"}}},"UsageRecordItemResponse":{"type":"object","required":["id","project_id","capability","quantity","unit","created_at"],"properties":{"capability":{"$ref":"#/components/schemas/Capability"},"created_at":{"type":"string","example":"2026-04-21T12:00:00Z"},"event_id":{"type":["integer","null"],"format":"int64"},"id":{"type":"integer","format":"int64","example":1},"project_id":{"type":"integer","format":"int64","example":3},"project_name":{"type":["string","null"]},"quantity":{"type":"string","example":"1"},"unit":{"$ref":"#/components/schemas/UsageUnit"}}},"UsageRecordsPayloadResponse":{"type":"object","required":["rows","total","has_more"],"properties":{"has_more":{"type":"boolean"},"limit":{"type":["integer","null"],"minimum":0},"page":{"type":["integer","null"],"minimum":0},"per_page":{"type":["integer","null"],"minimum":0},"rows":{"type":"array","items":{"$ref":"#/components/schemas/UsageRecordItemResponse"}},"total":{"type":"integer","minimum":0}}},"UsageSummaryDailyCallsResponse":{"type":"object","required":["date","capability","calls"],"properties":{"calls":{"type":"integer","minimum":0},"capability":{"$ref":"#/components/schemas/Capability"},"date":{"type":"string","example":"2026-04-21"}}},"UsageSummaryPayloadResponse":{"type":"object","required":["rows","daily_calls"],"properties":{"daily_calls":{"type":"array","items":{"$ref":"#/components/schemas/UsageSummaryDailyCallsResponse"}},"rows":{"type":"array","items":{"$ref":"#/components/schemas/UsageSummaryRowResponse"}}}},"UsageSummaryRowResponse":{"type":"object","required":["capability","unit","total_quantity","calls"],"properties":{"calls":{"type":"integer","minimum":0},"capability":{"$ref":"#/components/schemas/Capability"},"total_quantity":{"type":"string","example":"12.5"},"unit":{"$ref":"#/components/schemas/UsageUnit"}}},"UsageUnit":{"type":"string","enum":["audio_second","character","request","second"]},"UserState":{"type":"string","enum":["invalid","valid","suspended","rejected"]},"VerifyApiKeyResponse":{"type":"object","required":["tenant_id","user_id","project_id","api_key_id"],"properties":{"api_key_id":{"type":"integer","format":"int64"},"project_id":{"type":"integer","format":"int64"},"tenant_id":{"type":"integer","format":"int64"},"user_id":{"type":"integer","format":"int64"}}},"i64":{"type":"integer","format":"int64"}}},"tags":[{"name":"auth","description":"Google OAuth and session lifecycle endpoints"},{"name":"user","description":"Current user, onboarding, and admin user management endpoints"},{"name":"project","description":"Project and API key management endpoints"},{"name":"usage","description":"Usage reporting and query endpoints"}]}