SDK 操作手册

核心规则

SDK 是纯代码 SDK，不做 UI、CLI、配置文件发现或凭据存储。
初始化客户端时必须显式传入非空 API Key。
timeout 可以在客户端级别设置，也可以在单次请求里覆盖。
getSeaCloudDocs() 是离线文档入口，不需要客户端、不需要 API Key，也不发起网络请求。
生成任务默认读取模型契约，用于校验参数、补默认值并规划 queue 请求；契约服务暂不可用时，默认 auto 模式回退到原始 queue 请求。

服务域名

能力	SDK 使用的服务
LLM 对话	`https://cloud.vtrix.ai/llm`
生成 queue 生命周期	`https://cloud.seaart.ai`
模型规格	`https://cloud-model-spec.vtrix.ai`
SkillHub	`https://skill-hub.vtrix.ai/api/v1`

生成任务生命周期

flowchart TD
  User["调用 run / runSync"] --> ValidateInput["校验 modelId 和 params"]
  ValidateInput --> ReadSpec["读取模型契约"]
  ReadSpec --> PlanRequest["规划协议、bodyMode、queue endpoint 和 headers"]
  PlanRequest --> ValidateParams["校验参数并补契约默认值"]
  ValidateParams --> DryRun{"dryRun?"}
  DryRun -- 是 --> Preview["返回请求预览"]
  DryRun -- 否 --> Submit["POST 提交 queue 请求"]
  Submit --> Task["返回任务句柄"]
  Task --> Sync{"是否同步等待?"}
  Sync -- 否 --> Manual["调用方用 tasks.get / getResponse 查询"]
  Sync -- 是 --> Poll["轮询 statusUrl"]
  Poll --> Response["GET responseUrl"]
  Response --> Result["返回标准化结果"]

`run`：只创建任务

适合你要把任务 ID 存进数据库，或者把轮询交给后台 worker 的场景。

TypeScript
Python

const task = await client.run("wan25_t2i_preview", params, {
  timeout: 60_000,
  contract: "auto",
});

console.log(task.id, task.statusUrl, task.responseUrl);

task = await client.run("wan25_t2i_preview", params, {
    "timeout": 60_000,
    "contract": "auto",
})

print(task["id"], task.get("statusUrl"), task.get("responseUrl"))

`runSync`：创建任务并等待结果

适合请求方希望在一次 SDK 调用里拿到最终结果的场景。成功时，结果会把真实 response 放在 output.raw，并递归收集 url 字段到 output.urls。任务失败时返回 status: "failed" 和 error，不会伪造 output。

TypeScript
Python

const result = await client.runSync("wan25_t2i_preview", params, {
  timeout: 600_000,
});

if (result.status === "failed") {
  console.error(result.error?.message);
} else {
  console.log(result.output?.urls);
}

result = await client.run_sync("wan25_t2i_preview", params, {
    "timeout": 600_000,
})

if result["status"] == "failed":
    print(result.get("error", {}).get("message"))
else:
    print(result.get("output", {}).get("urls"))

`dryRun`：预览请求

dryRun 会走同一条模型契约规划路径，返回 endpoint、method、脱敏 headers、请求体和校验结果，但不会提交生成任务、不会轮询、不会读取 response。

TypeScript
Python

const preview = await client.run("wan25_t2i_preview", params, {
  dryRun: true,
});

console.log(preview.endpoint);
console.log(preview.request);

preview = await client.run("wan25_t2i_preview", params, dry_run=True)

print(preview["endpoint"])
print(preview["request"])

手动查询任务

tasks.get 读取任务状态；tasks.getResponse 读取最终 response。创建任务返回的 statusUrl / responseUrl 优先使用完整 URL；没有 URL 时再用 endpoint 拼接。

TypeScript
Python

const status = await client.tasks.get(task.id, {
  statusUrl: task.statusUrl,
  endpoint: "wan25_t2i_preview",
});

const finalResult = await client.tasks.getResponse(task.id, {
  responseUrl: status.responseUrl ?? task.responseUrl,
  endpoint: "wan25_t2i_preview",
});

status = await client.tasks.get(task["id"], {
    "statusUrl": task.get("statusUrl"),
    "endpoint": "wan25_t2i_preview",
})

final_result = await client.tasks.get_response(task["id"], {
    "responseUrl": status.get("responseUrl") or task.get("responseUrl"),
    "endpoint": "wan25_t2i_preview",
})

模型与 SkillHub

models.list：按分页、类型和关键词查询可用模型。
models.getSpec / models.get_spec：读取模型参数、协议、body mode、endpoint 和 Agent prompt。生成方法默认会自动读取同一份契约；当你要提前解释参数或做 UI 表单时，再主动调用。
skills.find：按关键词搜索 SkillHub 技能。
skills.list：分页列出 SkillHub 技能。

错误处理

常见 SDK 错误包括：

错误	场景
`AuthError`	API Key 缺失、无效或无权限。
`BalanceError`	余额不足。
`ValidationError`	SDK 本地参数校验失败。
`ModelNotFoundError`	模型不存在或模型规格不可读取。
`NetworkError`	HTTP 非 2xx 或网络异常。
`TimeoutError`	单次 HTTP 请求超时。
`TaskTimeoutError`	同步等待任务结果超时。

TypeScript 和 Python 都可以用 isSeaCloudError(error) 判断 SDK 错误，并读取 type、message、hint 等稳定字段。

语言差异

主题	TypeScript	Python
异步模型	Promise / async iterator	coroutine / async iterator
命名	camelCase	snake_case 优先，保留 camelCase 兼容别名
可选参数	option object	dict 或关键字参数
错误	throw SDK error	raise SDK error
dry run 返回	重载返回 `DryRunResult`	dict 返回 `dryRun: True`