# SeaCloud SDK AI Usage

This document is optimized for AI agents, coding assistants, and automated test
harnesses that need to call `@seacloudai/sdk` with minimal context.

## Install

```bash
pnpm add @seacloudai/sdk
```

`@seacloudai/sdk` publishes ESM and CommonJS entrypoints with TypeScript
declarations. Use `import` from ESM projects and `require` from CommonJS
projects.

## Safety Rule

Do not put the API key in browser code. Use the SDK from trusted server-side
code, or call it behind your own backend route.

## Minimal Import

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

```js
const { SeaCloud, getSeaCloudDocs } = require("@seacloudai/sdk");
```

Use `getSeaCloudDocs()` first when an AI agent needs to inspect the package
offline. It does not require an API key and does not make network requests.

```ts
const docs = getSeaCloudDocs();
console.log(docs.quickStart.content);
console.table(docs.methods);
```

Chinese documentation is available with:

```ts
const zhDocs = getSeaCloudDocs({ locale: "zh-CN" });
```

## Create a Client

```ts
const client = new SeaCloud({
  apiKey: process.env.SEACLOUD_API_KEY!,
  timeout: 600_000,
});
```

The SDK uses production service endpoints by default. Maintainers generate
those packaged defaults from env files such as `.env.prod`; it never reads
`apiKey` by itself. The caller must pass a non-empty `apiKey` explicitly.

## Generate

Create an async queue task:

```ts
const task = await client.run("gpt_image_2", {
  prompt: "a photorealistic orange tabby cat by a sunny window",
  n: 1,
  size: "1024x1024",
  output_format: "png",
  quality: "auto",
  moderation: "auto",
});
```

Create a task and wait for the final response:

```ts
const result = await client.runSync("gpt_image_2", {
  prompt: "a photorealistic orange tabby cat by a sunny window",
  n: 1,
  size: "1024x1024",
  output_format: "png",
  quality: "auto",
  moderation: "auto",
});

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

Preview a request without sending it:

```ts
const preview = await client.run("gpt_image_2", { prompt: "cat" }, {
  dryRun: true,
});
```

By default, `run` and `runSync` read the model contract to resolve protocol, body mode, endpoint, and contract headers. When `input_schema.required` is non-empty, the SDK only checks those top-level fields are present; model-specific type, format, range, default, and mutual-exclusion rules are handled by the API. `contract: "auto"` can fall back to raw queue JSON when the contract is unavailable; use `contract: "off"` only when you explicitly want raw passthrough behavior. Pass JavaScript objects as `params`; string flag syntax is not accepted.

## Handle Errors

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

try {
  await client.runSync("gpt_image_2", { prompt: "cat" });
} catch (error) {
  if (isSeaCloudError(error)) {
    console.error(error.type, error.message, error.hint);
  }
}
```