{
  "object": "cloudapi_help",
  "service": "Cloudapi",
  "version": "0.1.0",
  "publicBaseUrl": "https://cloudapi.szlk.ai",
  "environment": "development",
  "auth": {
    "type": "bearer",
    "header": "Authorization: Bearer <PROJECT_KEY>",
    "note": "项目身份、权限、配额与路由均由 project key 决定，请不要再传 X-Project-ID 一类项目头。"
  },
  "permissionModel": {
    "type": "capability_scoped",
    "permissions": [
      "analytics",
      "connections",
      "database",
      "ops",
      "github",
      "google",
      "gmail",
      "youtube",
      "x",
      "linkedin",
      "wechat",
      "assets",
      "identity",
      "chat",
      "models",
      "embeddings",
      "email",
      "search",
      "extract",
      "payments",
      "pdf",
      "community_search",
      "images",
      "speech",
      "speech_to_speech",
      "sfx_generation",
      "music",
      "voice",
      "3d",
      "videos",
      "video_upscale"
    ],
    "compatibilityNote": "未声明正式能力权限的历史 key 当前仍按兼容模式放行；一旦声明正式能力权限，则按该权限集合严格校验。"
  },
  "architecture": {
    "role": "capability_gateway",
    "note": "Cloudapi 只提供能力聚合、鉴权、配额与路由治理；多步业务编排、长任务状态机与异步 orchestration 必须放在上层应用或独立 runtime。"
  },
  "protocol": {
    "successEnvelope": [
      "id",
      "status",
      "capability",
      "provider",
      "model",
      "data",
      "usage",
      "meta"
    ],
    "errorEnvelope": [
      "message",
      "type",
      "code",
      "capability",
      "provider",
      "retryable"
    ],
    "assetStrategy": {
      "defaultMode": "binary",
      "optionalModes": [
        "asset",
        "url"
      ],
      "note": "图片/视频默认已走资产引用；音频能力可通过 response_format=asset|url 落 R2 并返回 asset 引用。"
    }
  },
  "structuredOutput": {
    "summary": "Cloudapi chat 已正式支持 response_format + structured_output contract，并保持 OpenAI 兼容 content 形状不变。",
    "scope": "当前闭环范围覆盖 non-stream 与 stream chat completions；旧项目仍可继续读取 choices[0].message.content。",
    "streamPolicy": "当 structured_output 与 stream=true 同时出现时，Cloudapi 会走缓冲式 SSE：内部先完成校验/repair/retry，再向客户端返回合法的 SSE 结果流。",
    "requestContract": {
      "response_format": {
        "type": "json_object | json_schema",
        "json_schema": {
          "name": "optional_schema_name",
          "schema": "{...json schema...}"
        }
      },
      "structured_output": {
        "strict": "boolean",
        "repair": "auto | never",
        "max_retries": "0..2",
        "on_validation_error": "retry | error"
      }
    },
    "errorCodes": {
      "unsupported": "STRUCTURED_OUTPUT_UNSUPPORTED",
      "schemaTooComplex": "STRUCTURED_OUTPUT_SCHEMA_TOO_COMPLEX",
      "validationFailed": "STRUCTURED_OUTPUT_VALIDATION_FAILED",
      "repairFailed": "STRUCTURED_OUTPUT_REPAIR_FAILED",
      "retryExhausted": "STRUCTURED_OUTPUT_RETRY_EXHAUSTED"
    },
    "providerMatrix": [
      {
        "provider": "gemini",
        "supports_json_object": true,
        "supports_json_schema": true,
        "supports_strict_tools": true,
        "supports_grammar_backend": false,
        "supports_repair_only": false,
        "notes": "Gemini native responseMimeType/responseSchema path."
      },
      {
        "provider": "vertex-ai",
        "supports_json_object": true,
        "supports_json_schema": true,
        "supports_strict_tools": true,
        "supports_grammar_backend": false,
        "supports_repair_only": false,
        "notes": "Vertex AI Gemini path follows the same native schema capability."
      },
      {
        "provider": "openai",
        "supports_json_object": true,
        "supports_json_schema": true,
        "supports_strict_tools": true,
        "supports_grammar_backend": false,
        "supports_repair_only": false,
        "notes": "OpenAI-compatible structured outputs path."
      },
      {
        "provider": "deepseek",
        "supports_json_object": true,
        "supports_json_schema": false,
        "supports_strict_tools": false,
        "supports_grammar_backend": false,
        "supports_repair_only": true,
        "notes": "JSON object mode only; schema strictness falls back to validate/repair."
      },
      {
        "provider": "openrouter",
        "supports_json_object": true,
        "supports_json_schema": false,
        "supports_strict_tools": false,
        "supports_grammar_backend": false,
        "supports_repair_only": true,
        "notes": "Gateway keeps OpenAI-compatible content shape and repairs when needed."
      },
      {
        "provider": "custom",
        "supports_json_object": true,
        "supports_json_schema": false,
        "supports_strict_tools": false,
        "supports_grammar_backend": false,
        "supports_repair_only": true,
        "notes": "OpenAI-compatible passthrough with Cloudapi-side validation/repair."
      }
    ],
    "helpers": {
      "javascript": "const CLOUDAPI_BASE_URL = 'https://cloudapi.szlk.ai';\n\nexport async function createStructuredChatCompletion({\n  apiKey,\n  model = 'auto',\n  messages,\n  schemaName = 'structured_payload',\n  schema = null,\n  strict = false\n}) {\n  const responseFormat = schema\n    ? {\n        type: 'json_schema',\n        json_schema: { name: schemaName, schema }\n      }\n    : { type: 'json_object' };\n\n  const res = await fetch(CLOUDAPI_BASE_URL + '/v1/chat/completions', {\n    method: 'POST',\n    headers: {\n      Authorization: 'Bearer ' + apiKey,\n      'Content-Type': 'application/json'\n    },\n    body: JSON.stringify({\n      model,\n      messages,\n      response_format: responseFormat,\n      structured_output: {\n        strict,\n        repair: 'auto',\n        max_retries: 1,\n        on_validation_error: 'retry'\n      }\n    })\n  });\n\n  const payload = await res.json();\n  if (!res.ok) {\n    throw new Error(payload?.error?.code + ': ' + payload?.error?.message);\n  }\n\n  return {\n    raw: payload,\n    structured: payload?.data?.structured ?? JSON.parse(payload.choices?.[0]?.message?.content || 'null'),\n    meta: payload?.data?.structured_output || null\n  };\n}",
      "typescript": "import { z } from 'zod';\n\ntype StructuredChatResult<T> = {\n  raw: any;\n  structured: T;\n  meta: {\n    requested: boolean;\n    path: string;\n    validated: boolean;\n    repaired: boolean;\n    retry_count: number;\n    failure_code: string | null;\n  } | null;\n};\n\nconst CLOUDAPI_BASE_URL = 'https://cloudapi.szlk.ai';\n\ntype ZodToJsonSchema = (schema: z.ZodTypeAny, name?: string) => Record<string, unknown>;\n\nexport async function createStructuredChatCompletionFromZod<T>({\n  apiKey,\n  model = 'auto',\n  messages,\n  zodSchema,\n  toJsonSchema,\n  schemaName = 'structured_payload',\n  strict = false\n}: {\n  apiKey: string;\n  model?: string;\n  messages: Array<{ role: string; content: unknown }>;\n  zodSchema: z.ZodType<T>;\n  toJsonSchema: ZodToJsonSchema;\n  schemaName?: string;\n  strict?: boolean;\n}): Promise<StructuredChatResult<T>> {\n  const schema = toJsonSchema(zodSchema, schemaName);\n\n  const res = await fetch(CLOUDAPI_BASE_URL + '/v1/chat/completions', {\n    method: 'POST',\n    headers: {\n      Authorization: 'Bearer ' + apiKey,\n      'Content-Type': 'application/json'\n    },\n    body: JSON.stringify({\n      model,\n      messages,\n      response_format: {\n        type: 'json_schema',\n        json_schema: { name: schemaName, schema }\n      },\n      structured_output: {\n        strict,\n        repair: 'auto',\n        max_retries: 1,\n        on_validation_error: 'retry'\n      }\n    })\n  });\n\n  const payload = await res.json();\n  if (!res.ok) {\n    throw new Error(String(payload?.error?.code || 'CLOUDAPI_ERROR') + ': ' + String(payload?.error?.message || 'Unknown error'));\n  }\n\n  const rawStructured = payload?.data?.structured ?? JSON.parse(payload.choices?.[0]?.message?.content || 'null');\n  const structured = zodSchema.parse(rawStructured) as T;\n  return {\n    raw: payload,\n    structured,\n    meta: payload?.data?.structured_output || null\n  };\n}",
      "python": "import json\nimport requests\nfrom pydantic import BaseModel\n\nCLOUDAPI_BASE_URL = \"https://cloudapi.szlk.ai\"\n\ndef create_structured_chat_completion_from_pydantic(\n    api_key,\n    messages,\n    model_class: type[BaseModel],\n    model=\"auto\",\n    schema_name=\"structured_payload\",\n    strict=False,\n):\n    schema = model_class.model_json_schema()\n\n    response = requests.post(\n        f\"{CLOUDAPI_BASE_URL}/v1/chat/completions\",\n        headers={\n            \"Authorization\": f\"Bearer {api_key}\",\n            \"Content-Type\": \"application/json\",\n        },\n        json={\n            \"model\": model,\n            \"messages\": messages,\n            \"response_format\": {\n                \"type\": \"json_schema\",\n                \"json_schema\": {\"name\": schema_name, \"schema\": schema},\n            },\n            \"structured_output\": {\n                \"strict\": strict,\n                \"repair\": \"auto\",\n                \"max_retries\": 1,\n                \"on_validation_error\": \"retry\",\n            },\n        },\n        timeout=120,\n    )\n\n    payload = response.json()\n    if not response.ok:\n        error = payload.get(\"error\") or {}\n        raise RuntimeError(f\"{error.get('code')}: {error.get('message')}\")\n\n    structured = payload.get(\"data\", {}).get(\"structured\")\n    if structured is None:\n        structured = json.loads(payload[\"choices\"][0][\"message\"][\"content\"])\n    structured = model_class.model_validate(structured)\n\n    return {\n        \"raw\": payload,\n        \"structured\": structured,\n        \"meta\": payload.get(\"data\", {}).get(\"structured_output\"),\n    }"
    }
  },
  "sdk": {
    "javascript": "\nconst baseUrl = 'https://cloudapi.szlk.ai';\nconst headers = {\n  Authorization: 'Bearer ' + process.env.CLOUDAPI_KEY,\n  'Content-Type': 'application/json'\n};\n\nexport async function createImage(prompt) {\n  const res = await fetch(baseUrl + '/v1/images/generations', {\n    method: 'POST',\n    headers,\n    body: JSON.stringify({ model: 'auto', prompt, response_format: 'url' })\n  });\n  return await res.json();\n}\n\nexport async function createSpeechAsset(text) {\n  const res = await fetch(baseUrl + '/v1/audio/speech', {\n    method: 'POST',\n    headers,\n    body: JSON.stringify({ model: 'auto', input: text, response_format: 'asset' })\n  });\n  return await res.json();\n}\n\nexport async function createVideo(prompt) {\n  const createRes = await fetch(baseUrl + '/v1/videos', {\n    method: 'POST',\n    headers,\n    body: JSON.stringify({ model: 'auto', prompt, duration: 5 })\n  });\n  const job = await createRes.json();\n  const pollRes = await fetch(baseUrl + job.meta.follow_up, { headers: { Authorization: headers.Authorization } });\n  return await pollRes.json();\n}\n      "
  },
  "endpoints": [
    {
      "id": "assets:create",
      "endpoint": "/v1/assets",
      "method": "POST",
      "permission": "assets",
      "summary": "上传或抓取资产并落到 Cloudapi R2。",
      "async": false
    },
    {
      "id": "assets:get",
      "endpoint": "/v1/assets/{assetId}",
      "method": "GET",
      "permission": "assets",
      "summary": "读取资产元数据。",
      "async": false
    },
    {
      "id": "assets:sign",
      "endpoint": "/v1/assets/{assetId}/sign",
      "method": "POST",
      "permission": "assets",
      "summary": "为资产生成临时签名访问链接。",
      "async": false
    },
    {
      "id": "analytics:events",
      "endpoint": "/v1/analytics/events",
      "method": "POST",
      "permission": "analytics",
      "summary": "将业务事件写入 SZLKanalytics 正式采集链路。",
      "async": false,
      "requestShape": {
        "event_name": "page_view",
        "anonymous_id": "anon_123",
        "page": "/dashboard",
        "properties": {
          "locale": "zh-CN"
        }
      }
    },
    {
      "id": "analytics:identify",
      "endpoint": "/v1/analytics/identify",
      "method": "POST",
      "permission": "analytics",
      "summary": "将匿名访客与实名主体对齐到 SZLKanalytics identity chain。",
      "async": false,
      "requestShape": {
        "anonymous_id": "anon_123",
        "canonical_user_id": "user_456",
        "resolution_source": "client_login"
      }
    },
    {
      "id": "analytics:overview",
      "endpoint": "/v1/analytics/overview",
      "method": "GET",
      "permission": "analytics",
      "summary": "读取 SZLKanalytics 经营概览。",
      "async": false
    },
    {
      "id": "analytics:briefings-latest",
      "endpoint": "/v1/analytics/briefings/latest",
      "method": "GET",
      "permission": "analytics",
      "summary": "读取 SZLKanalytics 最近一份日报摘要。",
      "async": false
    },
    {
      "id": "identity:cloudflare-access:me",
      "endpoint": "/v1/cloudflare/access/me",
      "method": "GET",
      "permission": "identity",
      "summary": "验证 Cloudflare Access 请求头并返回当前内部 staff subject。",
      "async": false
    },
    {
      "id": "identity:cloudflare-access:session",
      "endpoint": "/v1/cloudflare/access/session",
      "method": "GET",
      "permission": "identity",
      "summary": "返回 Cloudflare Access 重进后台/退出会话 helper；登录挑战仍由受保护业务 URL 自己触发。",
      "async": false,
      "requestShape": {
        "redirect_url": "absolute http(s) URL for post-login return",
        "audience": "optional audience narrowing hint for legacy callers"
      },
      "example": {
        "curl": "curl \"https://cloudapi.szlk.ai/v1/cloudflare/access/session?redirect_url=https%3A%2F%2Fpassport.szlk.ai%2Fpassport-admin%3Freauth%3D1\" \\\n  -H \"Authorization: Bearer $CLOUDAPI_PROJECT_KEY\""
      }
    },
    {
      "id": "identity:cloudflare-access:verify",
      "endpoint": "/v1/cloudflare/access/verify",
      "method": "POST",
      "permission": "identity",
      "summary": "验证 Cloudflare Access JWT，并按项目 staff policy 返回标准 staff subject。",
      "async": false,
      "requestShape": {
        "model": "auto?",
        "token": "Cloudflare Access JWT，服务端到服务端可选；默认读取 Cf-Access-Jwt-Assertion",
        "audience": "optional audience narrowing hint"
      },
      "example": {
        "curl": "curl https://cloudapi.szlk.ai/v1/cloudflare/access/me \\\n  -H \"Authorization: Bearer $CLOUDAPI_PROJECT_KEY\" \\\n  -H \"Cf-Access-Jwt-Assertion: $CF_ACCESS_JWT\"",
        "request": {
          "model": "auto",
          "token": "eyJ...",
          "audience": "optional-aud-tag"
        }
      }
    },
    {
      "id": "connections:oauth-start",
      "endpoint": "/v1/connections/oauth/start",
      "method": "POST",
      "permission": "connections",
      "summary": "启动外部连接 OAuth 授权流程。",
      "async": false
    },
    {
      "id": "google:oauth-start",
      "endpoint": "/v1/google/oauth/start",
      "method": "POST",
      "permission": "google",
      "summary": "启动 Google delegated OAuth 授权流程。",
      "async": false
    },
    {
      "id": "google:oauth-callback",
      "endpoint": "/v1/google/oauth/callback",
      "method": "GET",
      "permission": "google",
      "summary": "承接 Google delegated OAuth 回调。",
      "async": false
    },
    {
      "id": "gmail:oauth-start",
      "endpoint": "/v1/gmail/oauth/start",
      "method": "POST",
      "permission": "gmail",
      "summary": "启动 Gmail delegated/service OAuth 授权流程。",
      "async": false
    },
    {
      "id": "gmail:oauth-callback",
      "endpoint": "/v1/gmail/oauth/callback",
      "method": "GET",
      "permission": "gmail",
      "summary": "兼容 Gmail OAuth 回调入口；当前正式回调复用 /v1/google/oauth/callback。",
      "async": false
    },
    {
      "id": "youtube:oauth-start",
      "endpoint": "/v1/youtube/oauth/start",
      "method": "POST",
      "permission": "youtube",
      "summary": "启动 YouTube OAuth 授权流程。",
      "async": false
    },
    {
      "id": "youtube:oauth-callback",
      "endpoint": "/v1/youtube/oauth/callback",
      "method": "GET",
      "permission": "youtube",
      "summary": "承接 YouTube OAuth 回调。",
      "async": false
    },
    {
      "id": "x:oauth-start",
      "endpoint": "/v1/x/oauth/start",
      "method": "POST",
      "permission": "x",
      "summary": "启动 X OAuth 授权流程。",
      "async": false
    },
    {
      "id": "x:oauth-callback",
      "endpoint": "/v1/x/oauth/callback",
      "method": "GET",
      "permission": "x",
      "summary": "承接 X OAuth 回调。",
      "async": false
    },
    {
      "id": "linkedin:oauth-start",
      "endpoint": "/v1/linkedin/oauth/start",
      "method": "POST",
      "permission": "linkedin",
      "summary": "启动 LinkedIn OAuth 授权流程。",
      "async": false
    },
    {
      "id": "linkedin:oauth-callback",
      "endpoint": "/v1/linkedin/oauth/callback",
      "method": "GET",
      "permission": "linkedin",
      "summary": "承接 LinkedIn OAuth 回调。",
      "async": false
    },
    {
      "id": "wechat:oauth-start",
      "endpoint": "/v1/wechat/oauth/start",
      "method": "POST",
      "permission": "wechat",
      "summary": "启动 WeChat delegated OAuth 授权流程。",
      "async": false
    },
    {
      "id": "wechat:oauth-callback",
      "endpoint": "/v1/wechat/oauth/callback",
      "method": "GET",
      "permission": "wechat",
      "summary": "承接 WeChat delegated OAuth 回调。",
      "async": false
    },
    {
      "id": "connections:oauth-callback",
      "endpoint": "/v1/connections/oauth/callback/{provider}",
      "method": "GET",
      "permission": "connections",
      "summary": "承接外部连接 OAuth 回调。",
      "async": false
    },
    {
      "id": "connections:list",
      "endpoint": "/v1/connections",
      "method": "GET",
      "permission": "connections",
      "summary": "列出项目下的外部连接。",
      "async": false
    },
    {
      "id": "connections:import",
      "endpoint": "/v1/connections/import",
      "method": "POST",
      "permission": "connections",
      "summary": "导入已有 delegated external connection 凭证。",
      "async": false
    },
    {
      "id": "connections:oauth-provider-info",
      "endpoint": "/v1/connections/providers/{provider}/oauth-info",
      "method": "GET",
      "permission": "connections",
      "summary": "读取指定 OAuth provider 的共享 app 与回调元信息。",
      "async": false
    },
    {
      "id": "connections:get",
      "endpoint": "/v1/connections/{connectionId}",
      "method": "GET",
      "permission": "connections",
      "summary": "读取单个外部连接。",
      "async": false
    },
    {
      "id": "connections:events",
      "endpoint": "/v1/connections/{connectionId}/events",
      "method": "GET",
      "permission": "connections",
      "summary": "读取外部连接审计事件。",
      "async": false
    },
    {
      "id": "connections:snapshots",
      "endpoint": "/v1/connections/{connectionId}/snapshots",
      "method": "GET",
      "permission": "connections",
      "summary": "列出外部连接结果快照。",
      "async": false
    },
    {
      "id": "connections:snapshot-get",
      "endpoint": "/v1/connections/{connectionId}/snapshots/{snapshotId}",
      "method": "GET",
      "permission": "connections",
      "summary": "读取单个外部连接结果快照。",
      "async": false
    },
    {
      "id": "connections:delete",
      "endpoint": "/v1/connections/{connectionId}",
      "method": "DELETE",
      "permission": "connections",
      "summary": "删除单个外部连接。",
      "async": false
    },
    {
      "id": "connections:refresh",
      "endpoint": "/v1/connections/{connectionId}/refresh",
      "method": "POST",
      "permission": "connections",
      "summary": "刷新外部连接 access token。",
      "async": false
    },
    {
      "id": "github:repos",
      "endpoint": "/v1/github/repos",
      "method": "GET",
      "permission": "github",
      "summary": "列出 GitHub 可访问仓库。",
      "async": false
    },
    {
      "id": "github:repo-get",
      "endpoint": "/v1/github/repos/{owner}/{repo}",
      "method": "GET",
      "permission": "github",
      "summary": "读取单个 GitHub 仓库。",
      "async": false
    },
    {
      "id": "github:commits",
      "endpoint": "/v1/github/repos/{owner}/{repo}/commits",
      "method": "GET",
      "permission": "github",
      "summary": "列出 GitHub 仓库 commits。",
      "async": false
    },
    {
      "id": "github:pulls",
      "endpoint": "/v1/github/repos/{owner}/{repo}/pulls",
      "method": "GET",
      "permission": "github",
      "summary": "列出 GitHub 仓库 pull requests。",
      "async": false
    },
    {
      "id": "github:workflow-dispatch",
      "endpoint": "/v1/github/repos/{owner}/{repo}/actions/workflows/{workflowId}/dispatches",
      "method": "POST",
      "permission": "github",
      "summary": "触发 GitHub workflow dispatch。",
      "async": false,
      "requestShape": {
        "ref": "string",
        "inputs": "object?"
      }
    },
    {
      "id": "github:repository-dispatch",
      "endpoint": "/v1/github/repos/{owner}/{repo}/dispatches",
      "method": "POST",
      "permission": "github",
      "summary": "触发 GitHub repository dispatch。",
      "async": false,
      "requestShape": {
        "event_type": "string",
        "client_payload": "object?"
      }
    },
    {
      "id": "github:workflow-runs",
      "endpoint": "/v1/github/repos/{owner}/{repo}/actions/runs",
      "method": "GET",
      "permission": "github",
      "summary": "列出 GitHub workflow runs。",
      "async": false
    },
    {
      "id": "github:workflow-run-get",
      "endpoint": "/v1/github/repos/{owner}/{repo}/actions/runs/{runId}",
      "method": "GET",
      "permission": "github",
      "summary": "读取单个 GitHub workflow run。",
      "async": false
    },
    {
      "id": "github:workflow-run-rerun",
      "endpoint": "/v1/github/repos/{owner}/{repo}/actions/runs/{runId}/rerun",
      "method": "POST",
      "permission": "github",
      "summary": "重新执行 GitHub workflow run。",
      "async": false,
      "requestShape": {
        "enable_debug_logging": "boolean?"
      }
    },
    {
      "id": "github:workflow-run-cancel",
      "endpoint": "/v1/github/repos/{owner}/{repo}/actions/runs/{runId}/cancel",
      "method": "POST",
      "permission": "github",
      "summary": "取消 GitHub workflow run。",
      "async": false
    },
    {
      "id": "google-search-console:sites",
      "endpoint": "/v1/google/search-console/sites",
      "method": "GET",
      "permission": "google",
      "summary": "列出 Google Search Console 可访问站点。",
      "async": false
    },
    {
      "id": "google-search-console:search-analytics",
      "endpoint": "/v1/google/search-console/search-analytics/query",
      "method": "POST",
      "permission": "google",
      "summary": "查询 Google Search Console Search Analytics。",
      "async": false
    },
    {
      "id": "gmail:drafts-create",
      "endpoint": "/v1/gmail/drafts",
      "method": "POST",
      "permission": "gmail",
      "summary": "创建 Gmail 草稿。",
      "async": false
    },
    {
      "id": "gmail:drafts-send",
      "endpoint": "/v1/gmail/drafts/{draftId}/send",
      "method": "POST",
      "permission": "gmail",
      "summary": "发送指定 Gmail 草稿。",
      "async": false
    },
    {
      "id": "gmail:messages-list",
      "endpoint": "/v1/gmail/messages",
      "method": "GET",
      "permission": "gmail",
      "summary": "按 Gmail 查询语法列出邮件。",
      "async": false
    },
    {
      "id": "gmail:messages-get",
      "endpoint": "/v1/gmail/messages/{messageId}",
      "method": "GET",
      "permission": "gmail",
      "summary": "读取单封 Gmail 邮件。",
      "async": false
    },
    {
      "id": "youtube:channels-me",
      "endpoint": "/v1/youtube/channels/me",
      "method": "GET",
      "permission": "youtube",
      "summary": "读取当前 YouTube 连接对应的频道信息。",
      "async": false
    },
    {
      "id": "youtube:videos-upload",
      "endpoint": "/v1/youtube/videos/upload",
      "method": "POST",
      "permission": "youtube",
      "summary": "上传 YouTube 视频。",
      "async": false
    },
    {
      "id": "youtube:video-metrics",
      "endpoint": "/v1/youtube/videos/{videoId}/metrics",
      "method": "GET",
      "permission": "youtube",
      "summary": "读取指定 YouTube 视频的反馈指标。",
      "async": false
    },
    {
      "id": "youtube:video-thumbnail-set",
      "endpoint": "/v1/youtube/videos/{videoId}/thumbnail",
      "method": "POST",
      "permission": "youtube",
      "summary": "为指定 YouTube 视频设置缩略图。",
      "async": false
    },
    {
      "id": "youtube:video-captions-upload",
      "endpoint": "/v1/youtube/videos/{videoId}/captions",
      "method": "POST",
      "permission": "youtube",
      "summary": "为指定 YouTube 视频上传字幕。",
      "async": false
    },
    {
      "id": "x:me",
      "endpoint": "/v1/x/me",
      "method": "GET",
      "permission": "x",
      "summary": "读取当前 X 连接对应的账号资料。",
      "async": false
    },
    {
      "id": "x:posts",
      "endpoint": "/v1/x/posts",
      "method": "POST",
      "permission": "x",
      "summary": "发布 X 帖子。",
      "async": false
    },
    {
      "id": "x:post-metrics",
      "endpoint": "/v1/x/posts/{postId}/metrics",
      "method": "GET",
      "permission": "x",
      "summary": "读取指定 X 帖子的反馈指标。",
      "async": false
    },
    {
      "id": "linkedin:me",
      "endpoint": "/v1/linkedin/me",
      "method": "GET",
      "permission": "linkedin",
      "summary": "读取当前 LinkedIn 连接对应的成员资料。",
      "async": false
    },
    {
      "id": "linkedin:organizations",
      "endpoint": "/v1/linkedin/organizations",
      "method": "GET",
      "permission": "linkedin",
      "summary": "列出当前 LinkedIn 连接可管理的组织页面。",
      "async": false
    },
    {
      "id": "linkedin:posts",
      "endpoint": "/v1/linkedin/posts",
      "method": "POST",
      "permission": "linkedin",
      "summary": "发布 LinkedIn 帖子。",
      "async": false
    },
    {
      "id": "linkedin:post-metrics",
      "endpoint": "/v1/linkedin/posts/{postId}/metrics",
      "method": "GET",
      "permission": "linkedin",
      "summary": "读取指定 LinkedIn 帖子的反馈指标。",
      "async": false
    },
    {
      "id": "wechat:me",
      "endpoint": "/v1/wechat/me",
      "method": "GET",
      "permission": "wechat",
      "summary": "读取当前 WeChat delegated OAuth 连接对应的用户信息。",
      "async": false
    },
    {
      "id": "wechat:service-access-token",
      "endpoint": "/v1/wechat/service/access-token",
      "method": "GET",
      "permission": "wechat",
      "summary": "读取当前 WeChat service connection 对应的稳定 access token，供服务端发稿与指标拉取使用。",
      "async": false
    },
    {
      "id": "chat",
      "endpoint": "/v1/chat/completions",
      "method": "POST",
      "permission": "chat",
      "summary": "文本与多模态对话生成，兼容 OpenAI Chat Completions。",
      "async": false,
      "requestShape": {
        "model": "string",
        "messages": "array",
        "stream": "boolean",
        "response_format": "{ type: json_object|json_schema }?",
        "structured_output": "{ strict?, repair?, max_retries?, on_validation_error? }?"
      },
      "example": {
        "curl": "curl -X POST https://cloudapi.szlk.ai/v1/chat/completions \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"gemini-2.5-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}'"
      }
    },
    {
      "id": "models",
      "endpoint": "/v1/models",
      "method": "GET",
      "permission": "models",
      "summary": "列出当前 key 在当前项目上下文下可见的模型。",
      "async": false
    },
    {
      "id": "database:clusters:list",
      "endpoint": "/v1/database/clusters",
      "method": "GET",
      "permission": "database",
      "summary": "List project database clusters."
    },
    {
      "id": "database:clusters:provision",
      "endpoint": "/v1/database/clusters/provision",
      "method": "POST",
      "permission": "database",
      "summary": "Provision or update a project database cluster.",
      "requestShape": {
        "project_id": "string",
        "name": "string",
        "database_pool_id": "string",
        "node_placement": "object",
        "namespace": "string",
        "ha_profile": "object",
        "backup_profile": "object"
      }
    },
    {
      "id": "database:clusters:get",
      "endpoint": "/v1/database/clusters/{clusterId}",
      "method": "GET",
      "permission": "database",
      "summary": "Get project database cluster status."
    },
    {
      "id": "database:containers:ensure",
      "endpoint": "/v1/database/containers/ensure",
      "method": "POST",
      "permission": "database",
      "summary": "Install and ready a project database container on a GitOps node.",
      "requestShape": {
        "database_cluster_id": "string",
        "agent_id": "string"
      }
    },
    {
      "id": "database:sql:execute",
      "endpoint": "/v1/database/sql",
      "method": "POST",
      "permission": "database",
      "summary": "Execute SQL against a project database.",
      "requestShape": {
        "database_cluster_id": "string",
        "sql": "string"
      }
    },
    {
      "id": "database:backups:list",
      "endpoint": "/v1/database/backups",
      "method": "GET",
      "permission": "database",
      "summary": "List project database backup records."
    },
    {
      "id": "database:sources:list",
      "endpoint": "/v1/database/sources",
      "method": "GET",
      "permission": "database",
      "summary": "List project data federation sources."
    },
    {
      "id": "database:sources:register",
      "endpoint": "/v1/database/sources/register",
      "method": "POST",
      "permission": "database",
      "summary": "Register or update a project data source.",
      "requestShape": {
        "id": "string",
        "type": "d1 | r2 | postgres | supabase | neon | external_api | cloudapi",
        "capability": "string",
        "isolation_level": "public | project | subject",
        "config_secret_ref": "string"
      }
    },
    {
      "id": "database:resources:register",
      "endpoint": "/v1/database/resources/register",
      "method": "POST",
      "permission": "database",
      "summary": "Register or update a governed federated resource.",
      "requestShape": {
        "source_id": "string",
        "name": "string",
        "kind": "dataset | rowset | asset_collection | connection_snapshot",
        "default_scope": "public_publishable | project_private | subject_private"
      }
    },
    {
      "id": "database:records:upsert",
      "endpoint": "/v1/database/records/upsert",
      "method": "POST",
      "permission": "database",
      "summary": "Upsert a governed row into a federated resource.",
      "requestShape": {
        "resource": "string",
        "record_id": "string",
        "scope": "public_publishable | project_private | subject_private",
        "subject_type": "string",
        "subject_id": "string",
        "data": "object"
      }
    },
    {
      "id": "database:query",
      "endpoint": "/v1/database/query",
      "method": "POST",
      "permission": "database",
      "summary": "Query a governed federated resource without exposing the backing store.",
      "requestShape": {
        "resource": "string",
        "scope": "public_publishable | project_private | subject_private",
        "subject_type": "string",
        "subject_id": "string",
        "filters": "object",
        "limit": "number"
      }
    },
    {
      "id": "embeddings",
      "endpoint": "/v1/embeddings",
      "method": "POST",
      "permission": "embeddings",
      "summary": "向量嵌入生成。",
      "async": false
    },
    {
      "id": "email:send",
      "endpoint": "/v1/email/send",
      "method": "POST",
      "permission": "email",
      "summary": "发送事务邮件。",
      "async": false
    },
    {
      "id": "payments:stripe-checkout-sessions",
      "endpoint": "/v1/payments/stripe/checkout-sessions",
      "method": "POST",
      "permission": "payments",
      "summary": "创建 Stripe Checkout Session。",
      "async": false,
      "requestShape": {
        "model": "auto",
        "mode": "subscription",
        "priceKey": "cloudwiki.pro.monthly",
        "quantity": 1,
        "successUrl": "https://example.com/billing/success",
        "cancelUrl": "https://example.com/pricing",
        "customerEmail": "user@example.com",
        "metadata": {
          "szlk_product": "cloudwiki"
        }
      }
    },
    {
      "id": "payments:stripe-portal-sessions",
      "endpoint": "/v1/payments/stripe/customer-portal-sessions",
      "method": "POST",
      "permission": "payments",
      "summary": "创建 Stripe Customer Portal Session。",
      "async": false,
      "requestShape": {
        "model": "auto",
        "customer": "cus_123",
        "returnUrl": "https://example.com/account/billing"
      }
    },
    {
      "id": "payments:stripe-subscription-get",
      "endpoint": "/v1/payments/stripe/subscriptions/{subscriptionId}",
      "method": "GET",
      "permission": "payments",
      "summary": "读取 Stripe subscription 原始对象。",
      "async": false
    },
    {
      "id": "payments:stripe-price-get",
      "endpoint": "/v1/payments/stripe/prices/{priceKey}",
      "method": "GET",
      "permission": "payments",
      "summary": "按项目价格关键字读取 Stripe price 原始对象。",
      "async": false
    },
    {
      "id": "payments:stripe-webhook",
      "endpoint": "/v1/payments/stripe/webhook",
      "method": "POST",
      "permission": "payments",
      "summary": "统一接收 Stripe webhook，验签、去重并路由到项目账务系统。",
      "async": false,
      "requestShape": {
        "stripeDashboardEndpoint": "https://cloudapi.szlk.ai/v1/payments/stripe/webhook?channel_id=channel-stripe-1"
      }
    },
    {
      "id": "ops:railway:projects:list",
      "endpoint": "/v1/ops/railway/projects",
      "method": "GET",
      "permission": "ops",
      "summary": "列出 Railway projects。",
      "async": false
    },
    {
      "id": "ops:railway:environments:list",
      "endpoint": "/v1/ops/railway/projects/{projectId}/environments",
      "method": "GET",
      "permission": "ops",
      "summary": "列出指定 Railway project 下的 environments。",
      "async": false
    },
    {
      "id": "ops:railway:services:list",
      "endpoint": "/v1/ops/railway/projects/{projectId}/services",
      "method": "GET",
      "permission": "ops",
      "summary": "列出指定 Railway project 下的 services。",
      "async": false
    },
    {
      "id": "ops:railway:deployments:list",
      "endpoint": "/v1/ops/railway/deployments",
      "method": "GET",
      "permission": "ops",
      "summary": "按 project/environment/service 条件列出 Railway deployments。",
      "async": false
    },
    {
      "id": "ops:railway:variables:list",
      "endpoint": "/v1/ops/railway/variables",
      "method": "GET",
      "permission": "ops",
      "summary": "读取指定 Railway environment/service 的变量集。",
      "async": false
    },
    {
      "id": "ops:railway:variables:upsert",
      "endpoint": "/v1/ops/railway/variables/upsert",
      "method": "POST",
      "permission": "ops",
      "summary": "批量写入 Railway environment/service 变量。",
      "async": false,
      "requestShape": {
        "project_id": "Railway project id",
        "environment_id": "Railway environment id",
        "service_id": "optional Railway service id",
        "variables": "{ KEY: VALUE }"
      }
    },
    {
      "id": "ops:railway:deployment:redeploy",
      "endpoint": "/v1/ops/railway/deployments/redeploy",
      "method": "POST",
      "permission": "ops",
      "summary": "触发 Railway deployment redeploy。",
      "async": false,
      "requestShape": {
        "deployment_id": "Railway deployment id",
        "use_previous_image_tag": "optional boolean"
      }
    },
    {
      "id": "ops:railway:deployment:restart",
      "endpoint": "/v1/ops/railway/deployments/restart",
      "method": "POST",
      "permission": "ops",
      "summary": "重启指定 Railway deployment。",
      "async": false,
      "requestShape": {
        "deployment_id": "Railway deployment id"
      }
    },
    {
      "id": "search",
      "endpoint": "/v1/search",
      "method": "POST",
      "permission": "search",
      "summary": "统一 Web Search / grounded search。",
      "async": false,
      "requestShape": {
        "model": "string",
        "query": "string",
        "site_restrict": "string?",
        "date_restrict": "string?",
        "region": "string?",
        "limit": "number?",
        "include_answer": "boolean?",
        "include_content": "boolean?",
        "include_images": "boolean?",
        "content_top_n": "number?",
        "provider_options": {
          "brave": {
            "extra_snippets": "boolean?"
          },
          "jina": {
            "token_budget": "number?"
          },
          "tavily": {
            "topic": "general|news|finance?",
            "search_depth": "basic|advanced?",
            "time_range": "day|week|month|year?"
          }
        }
      },
      "example": {
        "curl": "curl -X POST https://cloudapi.szlk.ai/v1/search \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\":\"auto\",\n    \"query\":\"best project management alternatives\",\n    \"site_restrict\":\"reddit.com\",\n    \"limit\":5,\n    \"include_answer\":true,\n    \"include_content\":true,\n    \"provider_options\":{\n      \"tavily\":{\"topic\":\"general\",\"search_depth\":\"advanced\"},\n      \"brave\":{\"extra_snippets\":true},\n      \"jina\":{\"token_budget\":120000}\n    }\n  }'",
        "response": {
          "data": {
            "results": [
              {
                "url": "https://example.com/result",
                "title": "Example Result",
                "snippet": "Brief summary",
                "content": "Optional enriched content",
                "content_level": "snippet"
              }
            ],
            "answer": "Optional native answer",
            "answer_source": "native"
          },
          "meta": {
            "provider_features": {
              "native_answer": true,
              "full_content": false,
              "extra_snippets": true
            },
            "provider_extensions": {
              "brave": {
                "extra_snippets": true,
                "include_content": true
              }
            }
          }
        }
      }
    },
    {
      "id": "extract",
      "endpoint": "/v1/extract",
      "method": "POST",
      "permission": "extract",
      "summary": "统一网页正文提取。",
      "async": false,
      "requestShape": {
        "url": "string",
        "format": "markdown|text|html?",
        "min_content_length": "number?",
        "timeout_ms": "number?"
      },
      "example": {
        "curl": "curl -X POST https://cloudapi.szlk.ai/v1/extract \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"url\":\"https://example.com/product\",\"format\":\"markdown\",\"min_content_length\":200}'"
      }
    },
    {
      "id": "pdf",
      "endpoint": "/v1/pdf",
      "method": "POST",
      "permission": "pdf",
      "summary": "使用 browser-rendering 或 browserless 渲染受保护页面或 HTML，并返回 PDF。",
      "async": false,
      "requestShape": {
        "url": "string?",
        "html": "string?",
        "cookies": "array?",
        "headers": "object?",
        "pdf_options": "object?",
        "goto_options": "object?",
        "response_format": "binary|asset|url?"
      },
      "example": {
        "curl": "curl -X POST https://cloudapi.szlk.ai/v1/pdf \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"url\":\"https://example.com/report/print\",\"filename\":\"report.pdf\",\"goto_options\":{\"waitUntil\":\"networkidle0\",\"timeout\":45000},\"pdf_options\":{\"format\":\"A4\",\"printBackground\":true,\"preferCSSPageSize\":true}}'"
      }
    },
    {
      "id": "community-collect:create",
      "endpoint": "/v1/community/collect",
      "method": "POST",
      "permission": "community_search",
      "summary": "创建异步社区采集任务。",
      "async": true,
      "followUp": "/v1/community/collect/{jobId}"
    },
    {
      "id": "community-collect:get",
      "endpoint": "/v1/community/collect/{jobId}",
      "method": "GET",
      "permission": "community_search",
      "summary": "查询异步社区采集任务结果。",
      "async": true
    },
    {
      "id": "community-search",
      "endpoint": "/v1/community/search",
      "method": "POST",
      "permission": "community_search",
      "summary": "统一平台级社区搜索。",
      "async": false,
      "requestShape": {
        "platform": "string",
        "atomic_capability": "string?",
        "query": "string",
        "subreddit": "string?",
        "sort_by": "string?",
        "time_range": "string?",
        "limit": "number?"
      },
      "example": {
        "curl": "curl -X POST https://cloudapi.szlk.ai/v1/community/search \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"platform\":\"reddit\",\"atomic_capability\":\"comments\",\"query\":\"project management tool\",\"subreddit\":\"saas\",\"limit\":20}'"
      }
    },
    {
      "id": "images",
      "endpoint": "/v1/images/generations",
      "method": "POST",
      "permission": "images",
      "summary": "图像生成。",
      "async": false
    },
    {
      "id": "speech",
      "endpoint": "/v1/audio/speech",
      "method": "POST",
      "permission": "speech",
      "summary": "文本转语音。",
      "async": false
    },
    {
      "id": "speech:sts",
      "endpoint": "/v1/audio/sts",
      "method": "POST",
      "permission": "speech_to_speech",
      "summary": "语音转语音。",
      "async": false
    },
    {
      "id": "music",
      "endpoint": "/v1/audio/music",
      "method": "POST",
      "permission": "music",
      "summary": "音乐生成。",
      "async": false
    },
    {
      "id": "audio:sfx",
      "endpoint": "/v1/audio/sfx",
      "method": "POST",
      "permission": "sfx_generation",
      "summary": "音效生成。",
      "async": false
    },
    {
      "id": "voice:catalog",
      "endpoint": "/v1/audio/voices",
      "method": "GET",
      "permission": "voice",
      "summary": "列出可用声音列表。",
      "async": false
    },
    {
      "id": "voice:clone",
      "endpoint": "/v1/audio/voices/clone",
      "method": "POST",
      "permission": "voice",
      "summary": "克隆声音。",
      "async": false
    },
    {
      "id": "voice:design-preview",
      "endpoint": "/v1/audio/voices/design-preview",
      "method": "POST",
      "permission": "voice",
      "summary": "生成声音设计预览。",
      "async": false
    },
    {
      "id": "voice:design-save",
      "endpoint": "/v1/audio/voices/design-save",
      "method": "POST",
      "permission": "voice",
      "summary": "保存声音设计结果。",
      "async": false
    },
    {
      "id": "3d:create",
      "endpoint": "/v1/3d/generations",
      "method": "POST",
      "permission": "3d",
      "summary": "3D 生成或 Tripo 3D 异步任务创建。",
      "async": true,
      "followUp": "/v1/3d/generations/{generationId}"
    },
    {
      "id": "3d:get",
      "endpoint": "/v1/3d/generations/{generationId}",
      "method": "GET",
      "permission": "3d",
      "summary": "查询 Tripo 3D 异步任务结果。",
      "async": true
    },
    {
      "id": "videos:create",
      "endpoint": "/v1/videos",
      "method": "POST",
      "permission": "videos",
      "summary": "视频生成任务创建。",
      "async": true,
      "followUp": "/v1/videos/{videoId}"
    },
    {
      "id": "videos:upscale",
      "endpoint": "/v1/videos/upscale",
      "method": "POST",
      "permission": "video_upscale",
      "summary": "视频超分任务创建。",
      "async": true,
      "followUp": "/v1/videos/{videoId}"
    },
    {
      "id": "videos:get",
      "endpoint": "/v1/videos/{videoId}",
      "method": "GET",
      "permission": "videos",
      "summary": "查询视频生成任务结果。",
      "async": true
    }
  ],
  "health": [
    "/healthz",
    "/readyz"
  ]
}