seacloudai-sdk 0.1.0

Python SDK for SeaCloud AI generation APIs.

seacloudai-sdk

English | 简体中文

Python SDK for SeaCloud AI generation APIs.

SeaCloud SDK is a multimodal task execution SDK designed for agents and developers. With one SeaCloud API key, it provides unified access to LLM, image, video, audio, 3D, and other models; supports model search, spec queries, task execution, and result tracking; and helps discover and manage professional skills for creative workflows through SkillHub.

Chinese operation manual: docs/SDK_OPERATION_MANUAL.zh-CN.md.

If you are new to Python, start with docs/PYTHON_LEARNING_NOTES.zh-CN.md. It explains the Python syntax and code flow used in this project file by file.

Install

pip install seacloudai-sdk

For local development in this repository:

python -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

Server-Side Usage

Use this SDK from trusted server-side Python code. Do not put the API key in browser code. For browser apps, call your own backend route and let that route use seacloudai-sdk.

import os
from seacloud_sdk import SeaCloud, getSeaCloudDocs, isSeaCloudError

docs = getSeaCloudDocs()
print(docs["quickStart"]["content"])

client = SeaCloud(api_key=os.environ["SEACLOUD_API_KEY"])

try:
    result = await client.run_sync("wan25_t2i_preview", {
        "prompt": "a photorealistic orange tabby cat by a sunny window",
        "n": 1,
        "size": "1024*1024",
    })
    print(result.get("output", {}).get("urls"))
except Exception as error:
    if isSeaCloudError(error):
        print(error.type, str(error), error.hint)

Overview

seacloudai-sdk is a pure code SDK. It exposes typed Python methods, returns data objects, and never reads apiKey from environment variables by itself. Callers must pass api_key or the compatible apiKey parameter explicitly.

Quick Start

from seacloud_sdk import SeaCloud, getSeaCloudDocs

docs = getSeaCloudDocs()
print([method["name"] for method in docs["methods"]])

client = SeaCloud(api_key="sk-...", timeout=600_000)

text = await client.chat.send("gpt-4.1", [
    {"role": "user", "content": "Hello"},
])

task = await client.run("wan25_t2i_preview", {
    "prompt": "a photorealistic orange tabby cat by a sunny window",
    "n": 1,
    "prompt_extend": True,
    "size": "1024*1024",
    "watermark": False,
})

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

result = await client.run_sync("wan25_t2i_preview", {
    "prompt": "a photorealistic orange tabby cat by a sunny window",
    "n": 1,
    "prompt_extend": True,
    "size": "1024*1024",
    "watermark": False,
})

print(result.get("output", {}).get("urls", [None])[0])

API Overview

Module	Method	Purpose
Docs	getSeaCloudDocs()	Read the offline SDK operation manual and agent / skill usage guide
Client	SeaCloud(options) / SeaCloud(api_key=...)	Create a client with an explicit apiKey
Chat	client.chat.send(model, messages, options)	Send a text chat request
Generation	client.run(model_id, params, options)	Create a contract-aware queue task and return a task handle immediately
Generation	client.run_sync(model_id, params, options)	Create a contract-aware queue task and wait for the final response
Models	client.models.list(options)	List available models
Models	client.models.get_spec(model_id)	Read model parameters and agent prompts
Tasks	client.tasks.get(task_id, {"endpoint": model_id})	Read queue task status
Tasks	client.tasks.get_response(task_id, {"responseUrl": url})	Read the final queue task response
Skills	client.skills.find(query, options)	Search SkillHub skills
Skills	client.skills.list(options)	List SkillHub skills
Version	client.version()	Read the SDK version

Client Options

client = SeaCloud(
    api_key="sk-...",
    timeout=600_000,
    fetch=my_async_fetch,
)

api_key is required and has no default value. The SDK also accepts apiKey as an equivalent parameter for compatibility with camelCase call conventions. timeout can be set at the client level or overridden for a single method call. fetch is optional and is useful for proxies, tests, or special runtimes.

Offline Docs

getSeaCloudDocs() does not initialize a client, does not require apiKey, and does not make network requests. It is suitable for agents, LLM tool calls, and test pages that need to inspect public SDK usage.

docs = getSeaCloudDocs()
zh_docs = getSeaCloudDocs({"locale": "zh-CN"})

print(docs["operationManual"]["content"])
print(docs["agentSkillUsage"]["content"])
print([method["name"] for method in docs["methods"]])

Generation Parameters

Generation methods use fixed syntax:

client.run(model_id, params, options)
client.run_sync(model_id, params, options)
client.runSync(model_id, params, options)  # compatibility alias

• model_id is the first positional argument. By default, the SDK reads the model contract first and resolves the queue submit address.
• params is the second positional argument and must be a dict. The SDK validates required fields, types, and constraints according to the model contract, then applies contract defaults.
• options["timeout"] overrides the timeout for this request or synchronous wait.
• options["dryRun"] or the dry_run=True keyword plans and previews the request without submitting a task, polling, or reading the final response.
• options["contract"] is optional and defaults to "auto". "strict" requires the contract to be readable and valid. "off" disables contract reads and falls back to raw queue passthrough.
• There is no onProgress. The current backend lifecycle APIs do not provide trustworthy progress, so the SDK does not invent progress events.

By default, the SDK reads the model contract inside run or run_sync. When a contract is available, the SDK plans the request from protocol, body_mode, and explicit queue submit endpoint data, then validates params before submission. If the contract only returns an underlying provider api.endpoint, the SDK keeps the SeaArt queue submit address /model/v1/queue/{model_id}. When the contract service is unavailable, default "auto" mode falls back to a raw JSON request to /model/v1/queue/{model_id}.

flowchart TD
  User["User calls run/run_sync"] --> ValidateInput["Validate model_id and params dict"]
  ValidateInput --> ReadSpec["Read model contract"]
  ReadSpec --> PlanRequest["Plan protocol, bodyMode, queue endpoint, headers"]
  PlanRequest --> ValidateParams["Validate params and apply contract defaults"]
  ValidateParams --> DryRun{"dryRun / dry_run?"}
  DryRun -- yes --> Preview["Return planned request preview"]
  DryRun -- no --> Submit["POST queue submit request"]
  Submit --> Task["Return task handle"]
  Task --> Sync{"run_sync?"}
  Sync -- no --> Done["Caller polls manually with tasks.get/get_response"]
  Sync -- yes --> Poll["Poll statusUrl"]
  Poll --> Response["GET responseUrl"]
  Response --> Result["Return normalized RunSyncResult"]

run: Create an Async Task

run reads the model contract by default, then submits according to the planned contract:

GET https://cloud-model-spec.vtrix.ai/api/v1/skill/models/{modelId}/spec
POST https://cloud.seaart.ai/model/v1/queue/{modelId}

task = await client.run("wan25_t2i_preview", {
    "prompt": "a cute orange tabby cat sitting by a sunny window, detailed fur, soft natural light, photorealistic",
    "n": 1,
    "prompt_extend": True,
    "size": "1024*1024",
    "watermark": False,
})

Task handle:

{
    "id": "mmsu_...",
    "status": "queued",
    "model": "wan25_t2i_preview",
    "statusUrl": "...",
    "responseUrl": "...",
    "cancelUrl": "...",
    "queuePosition": 0,
}

Async mode does not return output, because the final generation result does not exist when the task is created.

run_sync: Wait for Final Result

run_sync creates a task, polls statusUrl, requests responseUrl after completion, and wraps the real response in a stable structure.

result = await client.run_sync("wan25_t2i_preview", {
    "prompt": "a cute orange tabby cat sitting by a sunny window, detailed fur, soft natural light, photorealistic",
    "n": 1,
    "prompt_extend": True,
    "size": "1024*1024",
    "watermark": False,
})

Return shape:

{
    "id": "mmsu_...",
    "status": "completed",
    "model": "wan25_t2i_preview",
    "output": {
        "urls": ["https://..."],
        "raw": {"request_id": "mmsu_..."},
    },
}

Mapping rules:

• id: prefers request_id, then id, then the task creation ID.
• status: success states normalize to completed; failed states normalize to failed.
• output.urls: recursively extracts all url fields from the real response.
• output.raw: keeps the real response so model-specific fields are not lost.
• error: maps task failures from the real response. Failed results do not invent output.

dry_run

preview = await client.run("wan25_t2i_preview", {
    "prompt": "a cinematic photo of a cat astronaut",
    "n": 1,
}, {"dryRun": True})

preview = await client.run("wan25_t2i_preview", {"prompt": "cat"}, dry_run=True)

dry_run returns modelId, protocol, bodyMode, endpoint, method, redacted headers, the contract-planned request body, and validation, but it does not submit a generation task.

Manual Task Lookup After run

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

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

get_response returns the same structure as run_sync: successful results include output.urls and output.raw; failed results include error and do not invent output.

Service Domains

Capability	Domain
Chat	https://cloud.vtrix.ai
Queue task lifecycle	https://cloud.seaart.ai
Model specs	https://cloud-model-spec.vtrix.ai
SkillHub	https://skill-hub.vtrix.ai

Naming Compatibility

Python code should prefer snake_case: run_sync, models.get_spec, tasks.get_response, api_key, and dry_run. The SDK also keeps camelCase compatibility aliases: runSync, models.getSpec, tasks.getResponse, apiKey, and dryRun. Returned data uses the public protocol's camelCase fields, such as statusUrl, responseUrl, queuePosition, pageSize, and totalPages.

Development

.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest
.venv/bin/ruff check .
.venv/bin/mypy src

Architecture

src/seacloud_sdk/
  client.py              SeaCloud facade and resource assembly
  __init__.py            Public exports
  core/                  Runtime config, HTTP client, errors, version
  domain/                Model aliases, response mapping, task result normalization
  resources/             One aggregate resource class per SDK capability
  types/                 Public typed contracts grouped by capability
  utils/                 Small shared objects and URL helpers
skills/                  Project-local agent skills for SDK usage