SDK Operation Manual

Core Rules

• SDKs are pure-code packages. They do not provide UI, CLI prompts, config-file discovery, or credential storage.
• Client initialization requires an explicit non-empty API key.
• timeout can be configured at the client level and overridden per request.
• getSeaCloudDocs() is offline and requires neither a client nor an API key.
• Generation calls read model contracts by default to validate params, apply defaults, and plan queue requests. In default auto mode, temporary contract-service failures fall back to raw queue submission.

Service Domains

Capability	Service
LLM chat	https://cloud.vtrix.ai/llm
Queue task lifecycle	https://cloud.seaart.ai
Model specs	https://cloud-model-spec.vtrix.ai
SkillHub	https://skill-hub.vtrix.ai/api/v1

Generation Lifecycle

flowchart TD
  User["Call run / runSync"] --> ValidateInput["Validate modelId and params"]
  ValidateInput --> ReadSpec["Read model contract"]
  ReadSpec --> PlanRequest["Plan protocol, bodyMode, queue endpoint, and headers"]
  PlanRequest --> ValidateParams["Validate params and apply defaults"]
  ValidateParams --> DryRun{"dryRun?"}
  DryRun -- yes --> Preview["Return request preview"]
  DryRun -- no --> Submit["POST queue request"]
  Submit --> Task["Return task handle"]
  Task --> Sync{"Wait synchronously?"}
  Sync -- no --> Manual["Caller polls with tasks.get / getResponse"]
  Sync -- yes --> Poll["Poll statusUrl"]
  Poll --> Response["GET responseUrl"]
  Response --> Result["Return normalized result"]

run: Create A Task

Use this when the application stores the task ID or delegates polling to a worker.

TypeScript

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

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

Python

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

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

runSync: Wait For Result

Use this when the caller expects the final result in a single SDK call. On success, output.raw preserves the original response and output.urls recursively collects URL fields. On task failure, the SDK returns status: "failed" with error and does not invent output.

TypeScript

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);
}

Python

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: Preview A Request

dryRun uses the same model-contract planning path and returns endpoint, method, redacted headers, request body, and validation metadata. It does not submit a task, poll status, or read the final response.

TypeScript

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

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

Python

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

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

Poll Tasks Manually

tasks.get reads task status. tasks.getResponse reads the final response. Prefer complete statusUrl and responseUrl values returned by the API; use endpoint-based URL construction when those URLs are not available.

TypeScript

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",
});

Python

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",
})

Models And SkillHub

• models.list: list available models by page, type, and keywords.
• models.getSpec and models.get_spec: read model params, protocol, body mode, endpoints, and agent prompt. Generation calls read the same contract automatically by default; call this directly when building forms or explaining params before generation.
• skills.find: search SkillHub by keyword.
• skills.list: list SkillHub skills with pagination.

Errors

Common SDK errors:

Error	Scenario
AuthError	Missing, invalid, or unauthorized API key.
BalanceError	Insufficient balance.
ValidationError	Local SDK parameter validation failed.
ModelNotFoundError	Model is missing or model spec cannot be read.
NetworkError	HTTP non-2xx or network failure.
TimeoutError	Single HTTP request timed out.
TaskTimeoutError	Synchronous task wait timed out.

TypeScript and Python callers can use isSeaCloudError(error) to detect SDK errors and read stable fields such as type, message, and hint.

Language Differences

Topic	TypeScript	Python
Async model	Promise / async iterator	coroutine / async iterator
Naming	camelCase	snake_case first, with camelCase aliases
Optional params	option object	dict or keyword args
Errors	throws SDK errors	raises SDK errors
dry run result	overload returns DryRunResult	dict with dryRun: True