Cloudapi Help

const baseUrl = 'https://cloudapi.szlk.ai';
const headers = {
  Authorization: 'Bearer ' + process.env.CLOUDAPI_KEY,
  'Content-Type': 'application/json'
};

export async function createImage(prompt) {
  const res = await fetch(baseUrl + '/v1/images/generations', {
    method: 'POST',
    headers,
    body: JSON.stringify({ model: 'auto', prompt, response_format: 'url' })
  });
  return await res.json();
}

export async function createSpeechAsset(text) {
  const res = await fetch(baseUrl + '/v1/audio/speech', {
    method: 'POST',
    headers,
    body: JSON.stringify({ model: 'auto', input: text, response_format: 'asset' })
  });
  return await res.json();
}

export async function createVideo(prompt) {
  const createRes = await fetch(baseUrl + '/v1/videos', {
    method: 'POST',
    headers,
    body: JSON.stringify({ model: 'auto', prompt, duration: 5 })
  });
  const job = await createRes.json();
  const pollRes = await fetch(baseUrl + job.meta.follow_up, { headers: { Authorization: headers.Authorization } });
  return await pollRes.json();
}
      

Cloudapi chat 已正式支持 response_format + structured_output contract，并保持 OpenAI 兼容 content 形状不变。

{
  "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"
  }
}

{
  "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"
}

const CLOUDAPI_BASE_URL = 'https://cloudapi.szlk.ai';

export async function createStructuredChatCompletion({
  apiKey,
  model = 'auto',
  messages,
  schemaName = 'structured_payload',
  schema = null,
  strict = false
}) {
  const responseFormat = schema
    ? {
        type: 'json_schema',
        json_schema: { name: schemaName, schema }
      }
    : { type: 'json_object' };

  const res = await fetch(CLOUDAPI_BASE_URL + '/v1/chat/completions', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model,
      messages,
      response_format: responseFormat,
      structured_output: {
        strict,
        repair: 'auto',
        max_retries: 1,
        on_validation_error: 'retry'
      }
    })
  });

  const payload = await res.json();
  if (!res.ok) {
    throw new Error(payload?.error?.code + ': ' + payload?.error?.message);
  }

  return {
    raw: payload,
    structured: payload?.data?.structured ?? JSON.parse(payload.choices?.[0]?.message?.content || 'null'),
    meta: payload?.data?.structured_output || null
  };
}

import { z } from 'zod';

type StructuredChatResult<T> = {
  raw: any;
  structured: T;
  meta: {
    requested: boolean;
    path: string;
    validated: boolean;
    repaired: boolean;
    retry_count: number;
    failure_code: string | null;
  } | null;
};

const CLOUDAPI_BASE_URL = 'https://cloudapi.szlk.ai';

type ZodToJsonSchema = (schema: z.ZodTypeAny, name?: string) => Record<string, unknown>;

export async function createStructuredChatCompletionFromZod<T>({
  apiKey,
  model = 'auto',
  messages,
  zodSchema,
  toJsonSchema,
  schemaName = 'structured_payload',
  strict = false
}: {
  apiKey: string;
  model?: string;
  messages: Array<{ role: string; content: unknown }>;
  zodSchema: z.ZodType<T>;
  toJsonSchema: ZodToJsonSchema;
  schemaName?: string;
  strict?: boolean;
}): Promise<StructuredChatResult<T>> {
  const schema = toJsonSchema(zodSchema, schemaName);

  const res = await fetch(CLOUDAPI_BASE_URL + '/v1/chat/completions', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model,
      messages,
      response_format: {
        type: 'json_schema',
        json_schema: { name: schemaName, schema }
      },
      structured_output: {
        strict,
        repair: 'auto',
        max_retries: 1,
        on_validation_error: 'retry'
      }
    })
  });

  const payload = await res.json();
  if (!res.ok) {
    throw new Error(String(payload?.error?.code || 'CLOUDAPI_ERROR') + ': ' + String(payload?.error?.message || 'Unknown error'));
  }

  const rawStructured = payload?.data?.structured ?? JSON.parse(payload.choices?.[0]?.message?.content || 'null');
  const structured = zodSchema.parse(rawStructured) as T;
  return {
    raw: payload,
    structured,
    meta: payload?.data?.structured_output || null
  };
}

import json
import requests
from pydantic import BaseModel

CLOUDAPI_BASE_URL = "https://cloudapi.szlk.ai"

def create_structured_chat_completion_from_pydantic(
    api_key,
    messages,
    model_class: type[BaseModel],
    model="auto",
    schema_name="structured_payload",
    strict=False,
):
    schema = model_class.model_json_schema()

    response = requests.post(
        f"{CLOUDAPI_BASE_URL}/v1/chat/completions",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={
            "model": model,
            "messages": messages,
            "response_format": {
                "type": "json_schema",
                "json_schema": {"name": schema_name, "schema": schema},
            },
            "structured_output": {
                "strict": strict,
                "repair": "auto",
                "max_retries": 1,
                "on_validation_error": "retry",
            },
        },
        timeout=120,
    )

    payload = response.json()
    if not response.ok:
        error = payload.get("error") or {}
        raise RuntimeError(f"{error.get('code')}: {error.get('message')}")

    structured = payload.get("data", {}).get("structured")
    if structured is None:
        structured = json.loads(payload["choices"][0]["message"]["content"])
    structured = model_class.model_validate(structured)

    return {
        "raw": payload,
        "structured": structured,
        "meta": payload.get("data", {}).get("structured_output"),
    }

上传或抓取资产并落到 Cloudapi R2。

读取资产元数据。

为资产生成临时签名访问链接。

将业务事件写入 SZLKanalytics 正式采集链路。

{
  "event_name": "page_view",
  "anonymous_id": "anon_123",
  "page": "/dashboard",
  "properties": {
    "locale": "zh-CN"
  }
}

将匿名访客与实名主体对齐到 SZLKanalytics identity chain。

{
  "anonymous_id": "anon_123",
  "canonical_user_id": "user_456",
  "resolution_source": "client_login"
}

读取 SZLKanalytics 经营概览。

读取 SZLKanalytics 最近一份日报摘要。

验证 Cloudflare Access 请求头并返回当前内部 staff subject。

返回 Cloudflare Access 重进后台/退出会话 helper；登录挑战仍由受保护业务 URL 自己触发。

{
  "redirect_url": "absolute http(s) URL for post-login return",
  "audience": "optional audience narrowing hint for legacy callers"
}

curl "https://cloudapi.szlk.ai/v1/cloudflare/access/session?redirect_url=https%3A%2F%2Fpassport.szlk.ai%2Fpassport-admin%3Freauth%3D1" \
  -H "Authorization: Bearer $CLOUDAPI_PROJECT_KEY"

验证 Cloudflare Access JWT，并按项目 staff policy 返回标准 staff subject。

{
  "model": "auto?",
  "token": "Cloudflare Access JWT，服务端到服务端可选；默认读取 Cf-Access-Jwt-Assertion",
  "audience": "optional audience narrowing hint"
}

curl https://cloudapi.szlk.ai/v1/cloudflare/access/me \
  -H "Authorization: Bearer $CLOUDAPI_PROJECT_KEY" \
  -H "Cf-Access-Jwt-Assertion: $CF_ACCESS_JWT"

{
  "model": "auto",
  "token": "eyJ...",
  "audience": "optional-aud-tag"
}

启动外部连接 OAuth 授权流程。

启动 Google delegated OAuth 授权流程。

承接 Google delegated OAuth 回调。

启动 Gmail delegated/service OAuth 授权流程。

兼容 Gmail OAuth 回调入口；当前正式回调复用 /v1/google/oauth/callback。

启动 YouTube OAuth 授权流程。

承接 YouTube OAuth 回调。

启动 X OAuth 授权流程。

承接 X OAuth 回调。

启动 LinkedIn OAuth 授权流程。

承接 LinkedIn OAuth 回调。

启动 WeChat delegated OAuth 授权流程。

承接 WeChat delegated OAuth 回调。

承接外部连接 OAuth 回调。

列出项目下的外部连接。

导入已有 delegated external connection 凭证。

读取指定 OAuth provider 的共享 app 与回调元信息。

读取单个外部连接。

读取外部连接审计事件。

列出外部连接结果快照。

读取单个外部连接结果快照。

删除单个外部连接。

刷新外部连接 access token。

列出 GitHub 可访问仓库。

读取单个 GitHub 仓库。

列出 GitHub 仓库 commits。

列出 GitHub 仓库 pull requests。

触发 GitHub workflow dispatch。

{
  "ref": "string",
  "inputs": "object?"
}

触发 GitHub repository dispatch。

{
  "event_type": "string",
  "client_payload": "object?"
}

列出 GitHub workflow runs。

读取单个 GitHub workflow run。

重新执行 GitHub workflow run。

{
  "enable_debug_logging": "boolean?"
}

取消 GitHub workflow run。

列出 Google Search Console 可访问站点。

查询 Google Search Console Search Analytics。

创建 Gmail 草稿。

发送指定 Gmail 草稿。

按 Gmail 查询语法列出邮件。

读取单封 Gmail 邮件。

读取当前 YouTube 连接对应的频道信息。

上传 YouTube 视频。

读取指定 YouTube 视频的反馈指标。

为指定 YouTube 视频设置缩略图。

为指定 YouTube 视频上传字幕。

读取当前 X 连接对应的账号资料。

发布 X 帖子。

读取指定 X 帖子的反馈指标。

读取当前 LinkedIn 连接对应的成员资料。

列出当前 LinkedIn 连接可管理的组织页面。

发布 LinkedIn 帖子。

读取指定 LinkedIn 帖子的反馈指标。

读取当前 WeChat delegated OAuth 连接对应的用户信息。

读取当前 WeChat service connection 对应的稳定 access token，供服务端发稿与指标拉取使用。

文本与多模态对话生成，兼容 OpenAI Chat Completions。

{
  "model": "string",
  "messages": "array",
  "stream": "boolean",
  "response_format": "{ type: json_object|json_schema }?",
  "structured_output": "{ strict?, repair?, max_retries?, on_validation_error? }?"
}

curl -X POST https://cloudapi.szlk.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-2.5-flash","messages":[{"role":"user","content":"Hello"}]}'

列出当前 key 在当前项目上下文下可见的模型。

List project database clusters.

Provision or update a project database cluster.

{
  "project_id": "string",
  "name": "string",
  "database_pool_id": "string",
  "node_placement": "object",
  "namespace": "string",
  "ha_profile": "object",
  "backup_profile": "object"
}

Get project database cluster status.

Install and ready a project database container on a GitOps node.

{
  "database_cluster_id": "string",
  "agent_id": "string"
}

Execute SQL against a project database.

{
  "database_cluster_id": "string",
  "sql": "string"
}

List project database backup records.

List project data federation sources.

Register or update a project data source.

{
  "id": "string",
  "type": "d1 | r2 | postgres | supabase | neon | external_api | cloudapi",
  "capability": "string",
  "isolation_level": "public | project | subject",
  "config_secret_ref": "string"
}

Register or update a governed federated resource.

{
  "source_id": "string",
  "name": "string",
  "kind": "dataset | rowset | asset_collection | connection_snapshot",
  "default_scope": "public_publishable | project_private | subject_private"
}

Upsert a governed row into a federated resource.

{
  "resource": "string",
  "record_id": "string",
  "scope": "public_publishable | project_private | subject_private",
  "subject_type": "string",
  "subject_id": "string",
  "data": "object"
}

Query a governed federated resource without exposing the backing store.

{
  "resource": "string",
  "scope": "public_publishable | project_private | subject_private",
  "subject_type": "string",
  "subject_id": "string",
  "filters": "object",
  "limit": "number"
}

向量嵌入生成。

发送事务邮件。

创建 Stripe Checkout Session。

{
  "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"
  }
}

创建 Stripe Customer Portal Session。

{
  "model": "auto",
  "customer": "cus_123",
  "returnUrl": "https://example.com/account/billing"
}

读取 Stripe subscription 原始对象。

按项目价格关键字读取 Stripe price 原始对象。

统一接收 Stripe webhook，验签、去重并路由到项目账务系统。

{
  "stripeDashboardEndpoint": "https://cloudapi.szlk.ai/v1/payments/stripe/webhook?channel_id=channel-stripe-1"
}

列出 Railway projects。

列出指定 Railway project 下的 environments。

列出指定 Railway project 下的 services。

按 project/environment/service 条件列出 Railway deployments。

读取指定 Railway environment/service 的变量集。

批量写入 Railway environment/service 变量。

{
  "project_id": "Railway project id",
  "environment_id": "Railway environment id",
  "service_id": "optional Railway service id",
  "variables": "{ KEY: VALUE }"
}

触发 Railway deployment redeploy。

{
  "deployment_id": "Railway deployment id",
  "use_previous_image_tag": "optional boolean"
}

重启指定 Railway deployment。

{
  "deployment_id": "Railway deployment id"
}

统一 Web Search / grounded search。

{
  "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?"
    }
  }
}

curl -X POST https://cloudapi.szlk.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"auto",
    "query":"best project management alternatives",
    "site_restrict":"reddit.com",
    "limit":5,
    "include_answer":true,
    "include_content":true,
    "provider_options":{
      "tavily":{"topic":"general","search_depth":"advanced"},
      "brave":{"extra_snippets":true},
      "jina":{"token_budget":120000}
    }
  }'

{
  "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
      }
    }
  }
}

统一网页正文提取。

{
  "url": "string",
  "format": "markdown|text|html?",
  "min_content_length": "number?",
  "timeout_ms": "number?"
}

curl -X POST https://cloudapi.szlk.ai/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/product","format":"markdown","min_content_length":200}'

使用 browser-rendering 或 browserless 渲染受保护页面或 HTML，并返回 PDF。

{
  "url": "string?",
  "html": "string?",
  "cookies": "array?",
  "headers": "object?",
  "pdf_options": "object?",
  "goto_options": "object?",
  "response_format": "binary|asset|url?"
}

curl -X POST https://cloudapi.szlk.ai/v1/pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/report/print","filename":"report.pdf","goto_options":{"waitUntil":"networkidle0","timeout":45000},"pdf_options":{"format":"A4","printBackground":true,"preferCSSPageSize":true}}'

创建异步社区采集任务。

查询异步社区采集任务结果。

统一平台级社区搜索。

{
  "platform": "string",
  "atomic_capability": "string?",
  "query": "string",
  "subreddit": "string?",
  "sort_by": "string?",
  "time_range": "string?",
  "limit": "number?"
}

curl -X POST https://cloudapi.szlk.ai/v1/community/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"reddit","atomic_capability":"comments","query":"project management tool","subreddit":"saas","limit":20}'

图像生成。

文本转语音。

语音转语音。

音乐生成。

音效生成。

列出可用声音列表。

克隆声音。

生成声音设计预览。

保存声音设计结果。

3D 生成或 Tripo 3D 异步任务创建。

查询 Tripo 3D 异步任务结果。

视频生成任务创建。

视频超分任务创建。

查询视频生成任务结果。