---
name: seacloud-sdk
description: 当智能体需要集成或解释 @seacloudai/sdk TypeScript SDK、选择合适方法、初始化 SeaCloud、使用 timeout 或 dryRun、处理错误，或查找某个 SeaCloud SDK 专项技能时使用。
---

# SeaCloud SDK

只把 `@seacloudai/sdk` 当作代码 SDK 使用。不要引入 SDK 表面之外的行为，也不要添加基于环境变量的 API key 默认值。

## 规则

- 构造 `SeaCloud` 时必须显式传入 `apiKey`；它始终是必填项。
- 前端代理、测试或特殊运行时可以在构造时显式传入 `fetch`。
- 直接返回和消费 SDK 数据对象。
- 需要让 agent 或大模型先了解 SDK 用法时，优先调用离线入口 `getSeaCloudDocs()`；它不需要 `apiKey`，也不发起网络请求。
- 单次调用需要不同限制时，优先使用方法级 `timeout`。
- 只在 `run` 和 `runSync` 上使用 `dryRun: true`。
- 生成方法没有 `onProgress`；后端 queue 生命周期接口没有可信进度，SDK 不伪造进度。
- 对可恢复失败，捕获 `SeaCloudError` 子类或检查 `error.type`。

## 方法选择

| 需求                       | 方法                                        | 技能                                       |
| -------------------------- | ------------------------------------------- | ------------------------------------------ |
| 离线读取操作手册和技能用法 | `getSeaCloudDocs()`                         | 本文件                                     |
| 文本对话                   | `client.chat.send()`                        | `skills/seacloud-chat-send/SKILL.md`       |
| 创建 queue 任务            | `client.run(modelId, params, options?)`     | `skills/seacloud-run/SKILL.md`             |
| 创建任务并等待最终结果     | `client.runSync(modelId, params, options?)` | `skills/seacloud-run/SKILL.md`             |
| 列出模型                   | `client.models.list()`                      | `skills/seacloud-models-list/SKILL.md`     |
| 读取模型合约               | `client.models.getSpec()`                   | `skills/seacloud-models-get-spec/SKILL.md` |
| 查询任务状态               | `client.tasks.get()`                        | `skills/seacloud-tasks-get/SKILL.md`       |
| 查询任务结果               | `client.tasks.getResponse()`                | `skills/seacloud-tasks-get/SKILL.md`       |
| 搜索 SkillHub              | `client.skills.find()`                      | `skills/seacloud-skills-find/SKILL.md`     |
| 列出 SkillHub              | `client.skills.list()`                      | `skills/seacloud-skills-list/SKILL.md`     |
| 版本                       | `client.version()`                          | `skills/seacloud-version/SKILL.md`         |
| 错误                       | 错误类                                      | `skills/seacloud-errors/SKILL.md`          |

## 最小设置

```ts
import { SeaCloud, getSeaCloudDocs } from "@seacloudai/sdk";

const docs = getSeaCloudDocs();
console.log(docs.operationManual.content);

const client = new SeaCloud({
  apiKey: "sk-...",
  timeout: 600_000,
  fetch: globalThis.fetch,
});
```

`chat.send` 只用于 LLM 对话，直接请求 `POST https://cloud.seaart.ai/llm/chat/completions`，不会先读取模型契约。

`run`、`runSync` 只用于多模态 queue 生成，例如生图、生视频、音频或 3D；queue 任务创建、任务状态查询和 response 查询使用 queue 生命周期端点。

`client.models.getSpec(modelId)` 读取 `GET https://sea-cloud-admin-web.real-cloud.seaart.ai/api/v1/skill/model-contracts/{modelId}`；`run` / `runSync` 默认也读取这份契约。

## 生成调用

固定语法：

```ts
client.run(modelId, params, options?)
client.runSync(modelId, params, options?)
```

`modelId` 是第一个参数，`params` 是第二个参数。`run` 和 `runSync` 默认读取模型契约，用于规划 protocol、bodyMode、queue submit endpoint 和 headers；如果 `input_schema.required` 非空，SDK 只检查这些顶层必传字段是否存在，然后把调用方传入的 JSON 提交到 `https://cloud.seaart.ai/model/v1/queue/{modelId}`。模型业务参数的默认值、类型、范围、format 和互斥规则由接口校验，不由 SDK 本地拦截。`contract: "auto"` 是默认值，契约服务暂不可用时可回退 raw queue；`contract: "strict"` 要求契约可读且能规划请求；只有 `contract: "off"` 才完全跳过契约读取。SDK 的 `params` 始终是 JavaScript 对象，不接受字符串形式的命令参数，也不会自动上传本地文件。

```ts
const task = await client.run("gpt_image_2", {
  prompt: "Generate cute cats programming",
  n: 1,
  size: "1024x1024",
  output_format: "png",
  quality: "auto",
  moderation: "auto",
});

const result = await client.runSync("gpt_image_2", {
  prompt: "Generate cute cats programming",
  n: 1,
  size: "1024x1024",
  output_format: "png",
  quality: "auto",
  moderation: "auto",
});

console.log(task.statusUrl);
console.log(result.output?.urls);
```