{ "object": "cloudapi_help", "service": "Cloudapi", "version": "0.1.0", "publicBaseUrl": "https://cloudapi.szlk.ai", "environment": "production", "auth": { "type": "bearer", "header": "Authorization: Bearer ", "note": "项目身份、权限、配额与路由均由 project key 决定，请不要再传 X-Project-ID 一类项目头。" }, "permissionModel": { "type": "capability_scoped", "permissions": [ "analytics", "agent", "seo", "trends", "blog", "knowledge", "connections", "connections:credentials:read", "database", "ops:read", "ops:deploy", "ops:config:write", "ops:secrets:read", "ops:delete", "github", "google", "gmail", "youtube", "x", "linkedin", "wechat", "dev", "assets", "identity", "chat", "models", "embeddings", "email", "search", "extract", "payments:read", "payments:checkout:create", "payments:catalog:write", "payments:sandbox:execute", "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。" }, "integrationGuides": { "analytics": { "service": "SZLKanalytics", "contractVersion": "2026-08-23", "permission": "analytics", "auth": "Authorization: Bearer ", "credentialBoundary": "CLOUDAPI_PROJECT_KEY is server-only; never expose it to browsers, public environment variables, URLs, or logs.", "projectScope": "The authenticated project key is authoritative. Do not send project_id, product_id, X-Project-ID, or direct SZLKanalytics bridge credentials.", "directServicePolicy": "Business products use Cloudapi /v1/analytics/* only; analytics.szlk.ai /api/* is reserved for the trusted Cloudapi bridge.", "onboardingFlow": [ "Read this live /v1/help document and select endpoints with permission=analytics.", "Validate representative payloads through POST /v1/analytics/validate without writing.", "Send events with a stable event_id and treat HTTP 202 as queue ownership transfer.", "Use a durable product outbox for registration, payment, refund, and subscription lifecycle facts.", "Call identify only from the product server after resolving canonical_user_id from an authenticated session.", "Check GET /v1/analytics/projects/self before trusting freshness-sensitive analysis.", "Query standard results first; configure project metric or funnel models only when the standard contract is insufficient." ], "queryExamples": { "metrics": { "analysis": "metrics", "from": "2026-08-01", "to": "2026-08-19", "metrics": [ "website_visitors", "business_active_users" ] }, "configuredMetric": { "analysis": "model", "model_id": "activation_value", "group_by": "day" }, "configuredFunnel": { "analysis": "model", "model_id": "activation_path" }, "retention": { "analysis": "retention", "from": "2026-07-01", "to": "2026-08-19" }, "eventStats": { "analysis": "event_stats", "stats": [ { "id": "total_visits", "event_names": [ "page_view" ], "measure": "event_count", "scope": "all_time" }, { "id": "active_now", "event_names": [ "presence_ping" ], "measure": "unique_subjects", "scope": "realtime", "window_seconds": 180 } ] } }, "modelUpdateExample": { "expected_version": 0, "models": [ { "id": "activation_value", "kind": "metric", "name": "Activation value", "event_names": [ "activation" ], "measure": "event_count" }, { "id": "activation_path", "kind": "funnel", "name": "Activation path", "window_days": 7, "steps": [ { "name": "Registered", "event_names": [ "sign_up" ] }, { "name": "Activated", "event_names": [ "activation" ] } ] } ] }, "endpoints": [ { "id": "analytics:events", "method": "POST", "endpoint": "/v1/analytics/events", "async": true, "summary": "将业务事件写入 SZLKanalytics 正式采集链路。" }, { "id": "analytics:identify", "method": "POST", "endpoint": "/v1/analytics/identify", "async": true, "summary": "将匿名访客与实名主体对齐到 SZLKanalytics identity chain。" }, { "id": "analytics:models:get", "method": "GET", "endpoint": "/v1/analytics/models", "async": false, "summary": "读取当前项目的版本化自定义指标与漏斗模型。" }, { "id": "analytics:models:put", "method": "PUT", "endpoint": "/v1/analytics/models", "async": false, "summary": "使用 expected_version 原子替换当前项目的自定义指标与漏斗模型。" }, { "id": "analytics:overview", "method": "GET", "endpoint": "/v1/analytics/overview", "async": false, "summary": "读取 SZLKanalytics 经营概览。" }, { "id": "analytics:briefings-latest", "method": "GET", "endpoint": "/v1/analytics/briefings/latest", "async": false, "summary": "读取 SZLKanalytics 最近一份日报摘要。" }, { "id": "analytics:project-status", "method": "GET", "endpoint": "/v1/analytics/projects/self", "async": false, "summary": "读取当前项目的接入就绪、事件落库、身份映射与最近聚合状态。" }, { "id": "analytics:query", "method": "POST", "endpoint": "/v1/analytics/query", "async": false, "summary": "按当前项目查询标准指标、累计/实时事件统计、留存、收入、渠道、告警或已配置分析模型。" }, { "id": "analytics:validate", "method": "POST", "endpoint": "/v1/analytics/validate", "async": false, "summary": "不写入数据，验证事件合同并返回会命中的经营指标。" } ] } }, "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 = {\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;\n\nexport async function createStructuredChatCompletionFromZod({\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;\n toJsonSchema: ZodToJsonSchema;\n schemaName?: string;\n strict?: boolean;\n}): Promise> {\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": "trends:query", "endpoint": "/v1/trends/query", "method": "POST", "permission": "trends", "summary": "查询实时热搜、关键词热度、地区分布及相关搜索。", "async": false, "requestShape": { "model": "trends/interest/time-series@serpapi", "keywords": [ "coffee" ], "geo": "US", "time_range": "today 3-m" }, "responseShape": { "capability": "trends", "provider": "serpapi", "model": "trends/interest/time-series@serpapi", "data": { "source": "google_trends", "scale": "relative_0_100", "items": [] } }, "errorCodes": [ "invalid_trends_input", "invalid_trends_model", "trends_model_not_allowed", "trends_channel_unavailable", "trends_credential_missing", "trends_credential_rejected", "trends_upstream_error" ] }, { "id": "knowledge:query", "endpoint": "/v1/knowledge/query", "method": "POST", "permission": "knowledge", "summary": "向已授权知识库提问，返回答案、证据与限制。", "async": false, "requestShape": { "question": "如何重置密码？", "history": [] }, "contractVersion": "2026-09-12" }, { "id": "knowledge:citations:get", "endpoint": "/v1/knowledge/citations/{id}", "method": "GET", "permission": "knowledge", "summary": "读取回答引用的原文证据。", "async": false, "contractVersion": "2026-09-12" }, { "id": "knowledge:feedback", "endpoint": "/v1/knowledge/answers/{id}/feedback", "method": "POST", "permission": "knowledge", "summary": "反馈未解决的问题并请求跟进。", "async": false, "requestShape": { "question": "如何重置密码？", "rating": "unhelpful", "comment": "", "handoff": true }, "contractVersion": "2026-09-12" }, { "id": "agent:runs:create", "endpoint": "/v1/agents/runs", "method": "POST", "permission": "agent", "summary": "提交目标，由 Agent 执行并返回可查询的任务。", "async": true, "requestShape": { "agent_id": "Agent 标识", "user_id": "业务服务端确认的用户标识", "conversation_id": "会话标识（可选）", "message": "要完成的目标" }, "idempotency": "使用相同 Idempotency-Key 重试相同请求，返回原任务。" }, { "id": "agent:runs:get", "endpoint": "/v1/agents/runs/{runId}?user_id={userId}", "method": "GET", "permission": "agent", "summary": "查看原任务的进度和结果。", "async": false }, { "id": "agent:runs:message", "endpoint": "/v1/agents/runs/{runId}/messages", "method": "POST", "permission": "agent", "summary": "补充信息并继续原任务。", "async": true, "requestShape": { "user_id": "用户标识", "message": "补充的信息" } }, { "id": "agent:runs:artifact", "endpoint": "/v1/agents/runs/{runId}/artifacts/{artifactId}?user_id={userId}", "method": "GET", "permission": "agent", "summary": "下载任务生成的文件。", "async": false }, { "id": "assets:create", "endpoint": "/v1/assets", "method": "POST", "permission": "assets", "summary": "上传或抓取资产并落到 Cloudapi R2。", "async": false }, { "id": "assets:delete", "endpoint": "/v1/assets/{assetId}", "method": "DELETE", "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": true, "requestShape": { "event_name": "page_view", "anonymous_id": "anon_123", "page": "/dashboard", "properties": { "locale": "zh-CN" } }, "responseShape": { "status": "queued", "data": { "event_id": "uuid", "delivery_id": "uuid", "project_id": "authenticated project" } }, "errorCodes": [ "invalid_api_key", "rate_limit_exceeded", "analytics_project_mismatch", "analytics_queue_unavailable" ], "limits": { "properties_bytes": 16384, "event_name": "lower_snake_case, max 64" }, "delivery": "Cloudapi ingress queue; at-least-once delivery to SZLKanalytics", "idempotency": "event_id", "contractVersion": "2026-08-23", "revenueContract": { "transaction_events": [ "subscription_started", "subscription_renewed", "refund_issued" ], "subscription_events": [ "subscription_started", "subscription_renewed", "subscription_canceled" ], "required_transaction_properties": [ "amount", "currency" ], "required_subscription_properties": [ "subscription_id", "mrr_amount" ] } }, { "id": "analytics:identify", "endpoint": "/v1/analytics/identify", "method": "POST", "permission": "analytics", "summary": "将匿名访客与实名主体对齐到 SZLKanalytics identity chain。", "async": true, "requestShape": { "anonymous_id": "anon_123", "canonical_user_id": "user_456", "resolution_source": "client_login" }, "responseShape": { "status": "queued", "data": { "anonymous_id": "string", "canonical_user_id": "string", "delivery_id": "uuid" } }, "errorCodes": [ "invalid_api_key", "rate_limit_exceeded", "analytics_queue_unavailable" ], "delivery": "Cloudapi ingress queue; project-scoped identity backfill" }, { "id": "analytics:models:get", "endpoint": "/v1/analytics/models", "method": "GET", "permission": "analytics", "summary": "读取当前项目的版本化自定义指标与漏斗模型。", "async": false, "responseShape": { "status": "completed", "data": { "version": 0, "models": [] } }, "contractVersion": "2026-08-23" }, { "id": "analytics:models:put", "endpoint": "/v1/analytics/models", "method": "PUT", "permission": "analytics", "summary": "使用 expected_version 原子替换当前项目的自定义指标与漏斗模型。", "async": false, "requestShape": { "expected_version": 0, "models": [] }, "responseShape": { "status": "completed", "data": { "version": 1, "models": [] } }, "errorCodes": [ "analysis_models_version_conflict", "analysis_models_invalid" ], "contractVersion": "2026-08-23" }, { "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": "analytics:project-status", "endpoint": "/v1/analytics/projects/self", "method": "GET", "permission": "analytics", "summary": "读取当前项目的接入就绪、事件落库、身份映射与最近聚合状态。", "async": false, "responseShape": { "status": "completed", "data": { "status": "ready", "project_id": "authenticated project" } } }, { "id": "analytics:query", "endpoint": "/v1/analytics/query", "method": "POST", "permission": "analytics", "summary": "按当前项目查询标准指标、累计/实时事件统计、留存、收入、渠道、告警或已配置分析模型。", "async": false, "requestShape": { "analysis": "metrics|model|funnel|retention|revenue|channels|alerts|event_stats", "event_stats": [ { "id": "active_now", "event_names": [ "presence_ping" ], "measure": "unique_subjects", "scope": "realtime", "window_seconds": 180 } ] }, "responseShape": { "status": "completed", "data": { "project_id": "authenticated project", "rows": [] } }, "contractVersion": "2026-08-23" }, { "id": "analytics:validate", "endpoint": "/v1/analytics/validate", "method": "POST", "permission": "analytics", "summary": "不写入数据，验证事件合同并返回会命中的经营指标。", "async": false, "requestShape": { "event_name": "account_registered", "canonical_user_id": "user_456", "source": "product.api", "channel": "auth", "page": "/api/auth/register", "properties": {} }, "responseShape": { "status": "completed", "data": { "status": "valid", "metric_events": [ "sign_up" ] } } }, { "id": "blog:projects:list", "endpoint": "/v1/blog/projects", "method": "GET", "permission": "blog", "summary": "列出当前 Cloudapi 项目身份已绑定的 Blog 项目。", "async": false, "contractVersion": "2026-08-20" }, { "id": "blog:projects:dependencies", "endpoint": "/v1/blog/projects/{projectKey}/dependencies", "method": "GET", "permission": "blog", "summary": "读取 Blog 项目的站点、语言、作者与分类依赖。", "async": false, "contractVersion": "2026-08-20" }, { "id": "blog:posts:list", "endpoint": "/v1/blog/projects/{projectKey}/posts", "method": "GET", "permission": "blog", "summary": "列出 Blog 项目文章。", "async": false, "contractVersion": "2026-08-20" }, { "id": "blog:posts:get", "endpoint": "/v1/blog/projects/{projectKey}/posts/{postId}", "method": "GET", "permission": "blog", "summary": "读取文章与版本清单。", "async": false, "contractVersion": "2026-08-20" }, { "id": "blog:post-versions:get", "endpoint": "/v1/blog/projects/{projectKey}/posts/{postId}/versions/{versionId}", "method": "GET", "permission": "blog", "summary": "读取精确不可变文章版本。", "async": false, "contractVersion": "2026-08-20" }, { "id": "blog:posts:create", "endpoint": "/v1/blog/posts", "method": "POST", "permission": "blog", "summary": "向已授权的 Blog 项目提交新文章草稿。", "async": false, "requestShape": { "target_project_key": "project-key", "locale": "en", "slug": "article-slug", "version": { "title": "Title", "description": "Description", "content_markdown": "# Article" } }, "idempotency": "Idempotency-Key header", "contractVersion": "2026-08-20" }, { "id": "blog:post-versions:create", "endpoint": "/v1/blog/projects/{projectKey}/posts/{postId}/versions", "method": "POST", "permission": "blog", "summary": "为既有文章创建新的草稿版本。", "async": false, "requestShape": { "title": "Title", "description": "Description", "content_markdown": "# Article" }, "idempotency": "Idempotency-Key header", "contractVersion": "2026-08-20" }, { "id": "blog:posts:submit-review", "endpoint": "/v1/blog/projects/{projectKey}/posts/{postId}/submit-review", "method": "POST", "permission": "blog", "summary": "提交文章当前草稿版本进入审核。", "async": false, "contractVersion": "2026-08-20" }, { "id": "blog:posts:review", "endpoint": "/v1/blog/projects/{projectKey}/posts/{postId}/review", "method": "POST", "permission": "blog", "summary": "审核文章的精确版本。", "async": false, "requestShape": { "version_id": "uuid", "decision": "approved", "note": null }, "contractVersion": "2026-08-20" }, { "id": "blog:posts:publish", "endpoint": "/v1/blog/projects/{projectKey}/posts/{postId}/publish", "method": "POST", "permission": "blog", "summary": "发布或定时发布已审核的精确版本。", "async": false, "requestShape": { "version_id": "uuid", "scheduled_for": null, "reason": null }, "idempotency": "Idempotency-Key header", "contractVersion": "2026-08-20" }, { "id": "blog:posts:unpublish", "endpoint": "/v1/blog/projects/{projectKey}/posts/{postId}/unpublish", "method": "POST", "permission": "blog", "summary": "下架一篇已发布文章。", "async": false, "requestShape": { "reason": null }, "idempotency": "Idempotency-Key header", "contractVersion": "2026-08-20" }, { "id": "blog:posts:archive", "endpoint": "/v1/blog/projects/{projectKey}/posts/{postId}/archive", "method": "POST", "permission": "blog", "summary": "归档文章并保留完整审计记录。", "async": false, "requestShape": { "reason": null }, "idempotency": "Idempotency-Key header", "contractVersion": "2026-08-20" }, { "id": "blog:posts:status", "endpoint": "/v1/blog/projects/{projectKey}/posts/{postId}/status", "method": "GET", "permission": "blog", "summary": "读取文章审核、排期与发布状态。", "async": false, "contractVersion": "2026-08-20" }, { "id": "blog:posts:lifecycle-events", "endpoint": "/v1/blog/projects/{projectKey}/posts/{postId}/lifecycle-events", "method": "GET", "permission": "blog", "summary": "读取生命周期事件和消费投递状态。", "async": false, "contractVersion": "2026-08-20" }, { "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": "identity:cloudflare-access:policy", "endpoint": "/v1/cloudflare/access/policy", "method": "GET", "permission": "identity", "summary": "返回当前 Cloudapi 项目的 Cloudflare Access staff policy，用于业务系统复用统一后台访问保护。", "async": false }, { "id": "connections:oauth-start", "endpoint": "/v1/connections/oauth/start", "method": "POST", "permission": "connections", "summary": "启动外部连接 OAuth 授权流程。", "async": false }, { "id": "identity:github-oauth-start", "endpoint": "/v1/identity/github/oauth/start", "method": "POST", "permission": "identity", "summary": "使用 Cloudapi 托管的 GitHub OAuth app 启动一次性身份验证，不创建 delegated connection。", "async": false }, { "id": "identity:github-assertion-redeem", "endpoint": "/v1/identity/github/oauth/redeem", "method": "POST", "permission": "identity", "summary": "由原发起项目一次性兑换已验证的 GitHub 身份断言。", "async": false }, { "id": "identity:google-oauth-start", "endpoint": "/v1/identity/google/oauth/start", "method": "POST", "permission": "identity", "summary": "使用 Cloudapi 托管的 Google OAuth app 启动一次性身份验证，不创建 delegated connection。", "async": false }, { "id": "identity:google-assertion-redeem", "endpoint": "/v1/identity/google/oauth/redeem", "method": "POST", "permission": "identity", "summary": "由原发起项目一次性兑换已验证的 Google 身份断言。", "async": false }, { "id": "google:oauth-start", "endpoint": "/v1/google/oauth/start", "method": "POST", "permission": "google", "summary": "启动仅包含 openid/email/profile 的 Google 登录授权流程。", "async": false }, { "id": "google:search-console-oauth-start", "endpoint": "/v1/google/search-console/oauth/start", "method": "POST", "permission": "google", "summary": "启动独立的 Google Search Console delegated OAuth 授权流程。", "async": false }, { "id": "google:oauth-callback", "endpoint": "/v1/google/oauth/callback", "method": "GET", "permission": "identity", "summary": "承接 Google OAuth 回调，并按授权事务路由到身份断言或 delegated connection。", "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": "github:identity-oauth-callback", "endpoint": "/v1/connections/oauth/callback/github", "method": "GET", "permission": "connections", "summary": "承接 GitHub OAuth 回调，并按授权事务路由到身份断言或 delegated connection。", "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:service-credential", "endpoint": "/v1/connections/{connectionId}/service-credential", "method": "GET", "permission": "connections:credentials:read", "summary": "读取非 OAuth 分发服务连接的受控运行凭据。", "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": "google-search-console:url-inspection", "endpoint": "/v1/google/search-console/url-inspection/inspect", "method": "POST", "permission": "google", "summary": "检查单个 URL 在 Google Search Console 中的索引状态。", "async": false }, { "id": "seo-bing:sites", "endpoint": "/v1/seo/bing/sites", "method": "GET", "permission": "seo", "summary": "列出 Bing Webmaster 已接入站点。", "async": false }, { "id": "seo-bing:search-performance", "endpoint": "/v1/seo/bing/search-performance", "method": "POST", "permission": "seo", "summary": "读取 Bing 搜索曝光与点击。", "async": false }, { "id": "seo-bing:pages", "endpoint": "/v1/seo/bing/pages", "method": "POST", "permission": "seo", "summary": "读取 Bing 热门页面最新快照。", "async": false }, { "id": "seo-bing:queries", "endpoint": "/v1/seo/bing/queries", "method": "POST", "permission": "seo", "summary": "读取 Bing 查询词曝光、点击与平均排名。", "async": false }, { "id": "seo-bing:page-queries", "endpoint": "/v1/seo/bing/page-queries", "method": "POST", "permission": "seo", "summary": "读取 Bing 指定页面的查询词表现。", "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": "ops:cloudflare:d1:backup:verify", "endpoint": "/v1/ops/cloudflare/d1/backups/verify", "method": "POST", "permission": "ops:read", "summary": "验证一个受治理 Cloudflare D1 备份回执及其持久工件。", "async": false, "requestShape": { "receipt_id": "backup receipt id", "d1_database_id": "exact D1 database UUID" } }, { "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": "dev:articles", "endpoint": "/v1/dev/articles", "method": "POST", "permission": "dev", "summary": "发布 DEV Community 文章。", "async": false, "idempotency": "Idempotency-Key header" }, { "id": "email:send", "endpoint": "/v1/email/send", "method": "POST", "permission": "email", "summary": "发送事务邮件。", "async": false }, { "id": "payments:apple-transaction-verify", "endpoint": "/v1/payments/apple/transactions/verify", "method": "POST", "permission": "payments:read", "summary": "Verify one StoreKit signed transaction against the configured Apple app." }, { "id": "payments:apple-notification-verify", "endpoint": "/v1/payments/apple/notifications/verify", "method": "POST", "permission": "payments:read", "summary": "Verify and decode one App Store Server Notification V2 payload." }, { "id": "payments:apple-subscription-status", "endpoint": "/v1/payments/apple/subscriptions/{transactionId}", "method": "GET", "permission": "payments:read", "summary": "Read and verify current Apple subscription status for one transaction chain." }, { "id": "payments:nowpayments", "endpoint": "/v1/payments/nowpayments", "method": "POST", "permission": "payments:read", "permissions": [ "payments:read", "payments:checkout:create" ], "summary": "通过项目治理的 NOWPayments 渠道创建和查询链上收款。", "async": false, "requestShape": { "operation": "estimate", "input": { "amount": 25, "price_currency": "usd", "pay_currency": "btc" } }, "responseShape": { "capability": "payments", "provider": "nowpayments", "model": "payment/nowpayments/core@nowpayments", "data": {} }, "errorCodes": [ "invalid_nowpayments_input", "payments_model_not_allowed", "payments_channel_unavailable", "nowpayments_channel_missing_api_key", "nowpayments_credential_rejected", "nowpayments_rate_limited", "nowpayments_upstream_error" ] }, { "id": "payments:stripe-test-transactions", "endpoint": "/v1/payments/stripe/test-transactions", "method": "POST", "permission": "payments:sandbox:execute", "summary": "使用 Stripe Test Mode 非交互交易验证真实支付、Webhook 与业务权益链路。", "async": false, "requestShape": { "model": "auto", "operationId": "acceptance-2026-08-30-001", "mode": "payment", "priceKey": "product.plan", "productKey": "product", "planKey": "plan", "amountCents": 999, "currency": "gbp", "customerEmail": "acceptance@example.com", "metadata": { "feature_keys": "paid_subscription" } } }, { "id": "payments:stripe-test-transactions-cleanup", "endpoint": "/v1/payments/stripe/test-transactions/{operationId}/cleanup", "method": "POST", "permission": "payments:sandbox:execute", "summary": "清理一次 Stripe Test Mode 验收创建的临时订阅、客户和产品对象，保留不可变测试事件审计。", "async": false }, { "id": "payments:stripe-checkout-sessions", "endpoint": "/v1/payments/stripe/checkout-sessions", "method": "POST", "permission": "payments:checkout:create", "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-checkout-session-get", "endpoint": "/v1/payments/stripe/checkout-sessions/{sessionId}", "method": "GET", "permission": "payments:read", "summary": "读取 Stripe Checkout Session 原始对象，用于受控账务恢复。", "async": false }, { "id": "payments:stripe-checkout-session-list", "endpoint": "/v1/payments/stripe/checkout-sessions", "method": "GET", "permission": "payments:read", "summary": "按 PaymentIntent 反查 Stripe Checkout Session，用于受控账务恢复。", "async": false }, { "id": "payments:stripe-price-catalog-archive", "endpoint": "/v1/payments/stripe/price-catalog/archive", "method": "POST", "permission": "payments:catalog:write", "summary": "停用 Stripe Price，并在没有其他启用价格时归档所属 Product。", "async": false, "requestShape": { "model": "auto", "priceKey": "solomap.pro.yearly" } }, { "id": "payments:stripe-price-catalog-upsert", "endpoint": "/v1/payments/stripe/price-catalog", "method": "POST", "permission": "payments:catalog:write", "summary": "创建或复用 Stripe Product + Price，并用 lookup_key 幂等管理项目 priceKey。", "async": false, "requestShape": { "model": "auto", "productKey": "solomap", "productName": "SoloMap Pro", "priceKey": "solomap.pro.yearly", "lookupKey": "solomap.pro.yearly", "amountCents": 2900, "currency": "usd", "interval": "year", "planKey": "solomap_pro_early_access_yearly" } }, { "id": "payments:stripe-portal-sessions", "endpoint": "/v1/payments/stripe/customer-portal-sessions", "method": "POST", "permission": "payments:checkout:create", "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:read", "summary": "读取 Stripe subscription 原始对象。", "async": false }, { "id": "payments:stripe-price-get", "endpoint": "/v1/payments/stripe/prices/{priceKey}", "method": "GET", "permission": "payments:read", "summary": "按项目价格关键字读取 Stripe price 原始对象。", "async": false }, { "id": "payments:stripe-webhook", "endpoint": "/v1/payments/stripe/webhook", "method": "POST", "permission": "payments:read", "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:read", "summary": "列出 Railway projects。", "async": false }, { "id": "ops:railway:environments:list", "endpoint": "/v1/ops/railway/projects/{projectId}/environments", "method": "GET", "permission": "ops:read", "summary": "列出指定 Railway project 下的 environments。", "async": false }, { "id": "ops:railway:services:list", "endpoint": "/v1/ops/railway/projects/{projectId}/services", "method": "GET", "permission": "ops:read", "summary": "列出指定 Railway project 下的 services。", "async": false }, { "id": "ops:railway:deployments:list", "endpoint": "/v1/ops/railway/deployments", "method": "GET", "permission": "ops:read", "summary": "按 project/environment/service 条件列出 Railway deployments。", "async": false }, { "id": "ops:railway:variables:list", "endpoint": "/v1/ops/railway/variables", "method": "GET", "permission": "ops:read", "summary": "读取指定 Railway environment/service 的变量集。", "async": false }, { "id": "ops:railway:variables:upsert", "endpoint": "/v1/ops/railway/variables/upsert", "method": "POST", "permission": "ops:config:write", "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:deploy", "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:deploy", "summary": "重启指定 Railway deployment。", "async": false, "requestShape": { "deployment_id": "Railway deployment id" } }, { "id": "ops:vercel:domains:list", "endpoint": "/v1/ops/vercel/domains", "method": "GET", "permission": "ops:read", "summary": "列出 Vercel account/team 域名，用于释放项目迁移后残留的全局域名。", "async": false }, { "id": "ops:vercel:domain:remove", "endpoint": "/v1/ops/vercel/domains/remove", "method": "POST", "permission": "ops:delete", "summary": "从 Vercel account/team 删除一个域名，要求精确 confirm_domain。", "async": false, "requestShape": { "domain": "Vercel domain name", "confirm_domain": "must exactly match domain", "team_id": "optional Vercel team id", "team_slug": "optional Vercel team slug" } }, { "id": "ops:vercel:projects:list", "endpoint": "/v1/ops/vercel/projects", "method": "GET", "permission": "ops:read", "summary": "列出 Vercel projects。", "async": false }, { "id": "ops:vercel:deployments:list", "endpoint": "/v1/ops/vercel/deployments", "method": "GET", "permission": "ops:read", "summary": "按 project 条件列出 Vercel deployments。", "async": false }, { "id": "ops:vercel:deployment:get", "endpoint": "/v1/ops/vercel/deployments/{deploymentId}", "method": "GET", "permission": "ops:read", "summary": "读取指定 Vercel deployment。", "async": false }, { "id": "ops:vercel:variables:list", "endpoint": "/v1/ops/vercel/projects/{projectId}/variables", "method": "GET", "permission": "ops:read", "summary": "读取指定 Vercel project 的变量集。", "async": false }, { "id": "ops:vercel:variables:upsert", "endpoint": "/v1/ops/vercel/projects/{projectId}/variables/upsert", "method": "POST", "permission": "ops:config:write", "summary": "批量写入 Vercel project 变量。", "async": false, "requestShape": { "variables": "[{ key, value, type, target }]" } }, { "id": "ops:vercel:deployment:redeploy", "endpoint": "/v1/ops/vercel/deployments/redeploy", "method": "POST", "permission": "ops:deploy", "summary": "触发 Vercel deployment redeploy。", "async": false, "requestShape": { "deployment_id": "Vercel deployment id", "target": "optional deployment target", "with_latest_commit": "optional boolean" } }, { "id": "ops:neon:organizations:list", "endpoint": "/v1/ops/neon/organizations", "method": "GET", "permission": "ops:read", "summary": "列出 Neon organizations，用于发现组织级 projects 的 org_id。", "async": false }, { "id": "ops:neon:projects:list", "endpoint": "/v1/ops/neon/projects", "method": "GET", "permission": "ops:read", "summary": "列出 Neon projects。", "async": false }, { "id": "ops:neon:branches:list", "endpoint": "/v1/ops/neon/projects/{projectId}/branches", "method": "GET", "permission": "ops:read", "summary": "列出指定 Neon project 下的 branches。", "async": false }, { "id": "ops:neon:databases:list", "endpoint": "/v1/ops/neon/projects/{projectId}/branches/{branchId}/databases", "method": "GET", "permission": "ops:read", "summary": "列出指定 Neon branch 下的 databases。", "async": false }, { "id": "ops:neon:roles:list", "endpoint": "/v1/ops/neon/projects/{projectId}/branches/{branchId}/roles", "method": "GET", "permission": "ops:read", "summary": "列出指定 Neon branch 下的 roles。", "async": false }, { "id": "ops:neon:endpoints:list", "endpoint": "/v1/ops/neon/projects/{projectId}/endpoints", "method": "GET", "permission": "ops:read", "summary": "列出指定 Neon project 下的 compute endpoints。", "async": false }, { "id": "ops:neon:operations:list", "endpoint": "/v1/ops/neon/projects/{projectId}/operations", "method": "GET", "permission": "ops:read", "summary": "列出指定 Neon project 的 operations。", "async": false }, { "id": "ops:neon:connection-uri:get", "endpoint": "/v1/ops/neon/connection-uri", "method": "POST", "permission": "ops:secrets:read", "summary": "读取指定 Neon database 的 Postgres connection URI。", "async": false, "requestShape": { "project_id": "Neon project id", "branch_id": "optional Neon branch id", "endpoint_id": "optional Neon endpoint id", "database_name": "Neon database name", "role_name": "Neon role name", "pooled": "optional boolean" } }, { "id": "ops:supabase:organizations:list", "endpoint": "/v1/ops/supabase/organizations", "method": "GET", "permission": "ops:read", "summary": "列出 Supabase organizations。", "async": false }, { "id": "ops:supabase:projects:list", "endpoint": "/v1/ops/supabase/projects", "method": "GET", "permission": "ops:read", "summary": "列出 Supabase projects。", "async": false }, { "id": "ops:supabase:branches:list", "endpoint": "/v1/ops/supabase/projects/{projectRef}/branches", "method": "GET", "permission": "ops:read", "summary": "列出指定 Supabase project 下的 database branches。", "async": false }, { "id": "ops:supabase:database-context:get", "endpoint": "/v1/ops/supabase/projects/{projectRef}/database/context", "method": "GET", "permission": "ops:read", "summary": "读取指定 Supabase project 的 database metadata。", "async": false }, { "id": "ops:supabase:database-config:get", "endpoint": "/v1/ops/supabase/projects/{projectRef}/database/config", "method": "GET", "permission": "ops:read", "summary": "读取指定 Supabase project 的 Postgres 与 pooler 配置。", "async": false }, { "id": "ops:supabase:backups:list", "endpoint": "/v1/ops/supabase/projects/{projectRef}/database/backups", "method": "GET", "permission": "ops:read", "summary": "列出指定 Supabase project 的 database backups。", "async": false }, { "id": "ops:supabase:migrations:list", "endpoint": "/v1/ops/supabase/projects/{projectRef}/database/migrations", "method": "GET", "permission": "ops:read", "summary": "列出指定 Supabase project 的 migration history。", "async": false }, { "id": "ops:supabase:health:get", "endpoint": "/v1/ops/supabase/projects/{projectRef}/health", "method": "GET", "permission": "ops:read", "summary": "读取指定 Supabase project 的服务健康状态。", "async": false }, { "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" ] }