Руководство по работе с SDK

Основные правила

SDK являются pure-code пакетами. Они не предоставляют UI, CLI prompts, config-file discovery, credential storage, local file upload или shell-style flag parsing.
Инициализация клиента требует явный непустой API key. Приложение может сначала прочитать environment variable, но SDK сами не читают API keys из environment variables.
Выпущенные SDK поставляются с production service endpoints. Maintainer-only endpoint overrides записываются в package defaults во время build и не читаются из окружения вызывающего приложения в runtime.
timeout можно настроить на уровне клиента и переопределить для отдельного запроса.
getSeaCloudDocs() работает offline и не требует ни клиента, ни API key.
Generation calls по умолчанию читают model contracts, чтобы спланировать queue requests. SDK локально проверяет только top-level required fields из input_schema.required; model-specific type, format, range, default и mutual-exclusion rules обрабатываются API.

Service endpoints

Возможность	Endpoint
Chat	`POST https://cloud.seaart.ai/llm/chat/completions`
Model list	`GET https://sea-cloud-admin-web.real-cloud.seaart.ai/api/v1/skill/models`
Queue submit	`POST https://cloud.seaart.ai/model/v1/queue/{modelId}`
Queue status	`GET https://cloud.seaart.ai/model/v1/queue/{modelId}/requests/{request_id}/status`
Queue response	`GET https://cloud.seaart.ai/model/v1/queue/{modelId}/requests/{request_id}/response`
Model contract	`GET https://sea-cloud-admin-web.real-cloud.seaart.ai/api/v1/skill/model-contracts/{modelId}`
SkillHub search	`GET https://skill-hub.vtrix.ai/api/v1/search`
SkillHub list	`GET https://skill-hub.vtrix.ai/api/v1/skills`

Contract modes

Mode	Поведение
`auto`	Значение по умолчанию. SDK читает model contract, если возможно, планирует queue endpoint и headers, затем откатывается к raw queue JSON, если contract временно недоступен или отсутствует.
`strict`	Model contract должен быть доступен и пригоден для планирования. Ошибки чтения contract возвращаются вызывающему коду без fallback.
`off`	SDK пропускает чтение contract и отправляет caller-provided params как raw queue JSON.

Успешно прочитанные contracts могут кратко кэшироваться внутри процесса SDK. Используйте models.getSpec() или models.get_spec(), когда нужно напрямую посмотреть contract.

Жизненный цикл generation task

flowchart TD
  User["Вызов run / runSync"] --> ValidateInput["Проверить modelId и params object"]
  ValidateInput --> ContractMode{"Использовать contract mode?"}
  ContractMode -- "auto / strict" --> ReadContract["Прочитать model contract"]
  ContractMode -- "off" --> PlanRaw["Использовать raw queue request"]
  ReadContract --> PlanContract["Спланировать protocol, bodyMode, queue endpoint и headers"]
  ReadContract -- "auto недоступен" --> PlanRaw
  PlanContract --> RequiredFields["Проверить top-level fields из input_schema.required"]
  PlanRaw --> DryRun{"dryRun?"}
  RequiredFields --> DryRun
  DryRun -- "да" --> Preview["Вернуть request preview"]
  DryRun -- "нет" --> Submit["POST queue request"]
  Submit --> Task["Вернуть task handle"]
  Task --> Sync{"Ждать синхронно?"}
  Sync -- "нет" --> Manual["Caller polls через tasks.get / getResponse"]
  Sync -- "да" --> Poll["Опросить statusUrl"]
  Poll --> Response["GET responseUrl"]
  Response --> Result["Вернуть normalized result"]

`run`: создать task

Используйте run, когда приложение сохраняет task ID или передает polling отдельному worker.

TypeScript
Python

const params = {
  prompt: "Generate cute cats programming",
  n: 1,
  size: "1024x1024",
  output_format: "png",
  quality: "auto",
  moderation: "auto",
};

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

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

params = {
    "prompt": "Generate cute cats programming",
    "n": 1,
    "size": "1024x1024",
    "output_format": "png",
    "quality": "auto",
    "moderation": "auto",
}

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

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

run возвращает task handle. В нем нет final output, потому что queue response доступен только после завершения task.

`runSync`: дождаться результата

Используйте runSync, когда вызывающий код ожидает final result в одном SDK call. При успехе output.raw сохраняет исходный response, а output.urls рекурсивно собирает URL fields. При task failure SDK возвращает status: "failed" с error и не придумывает output.

TypeScript
Python

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

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

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

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

runSync / run_sync опрашивает task status с bounded backoff и читает responseUrl после completion. Общая длительность ожидания все равно ограничена настроенным timeout.

`dryRun`: preview request

dryRun использует тот же planning path, что и реальный generation call, и возвращает endpoint, method, redacted headers, request body и validation metadata. Он не создает task, не опрашивает status и не читает final response.

Когда включен contract mode, dryRun может прочитать model contract и локально проверяет только top-level fields из input_schema.required.

TypeScript
Python

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

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

preview = await client.run("gpt_image_2", {
    "prompt": "Generate cute cats programming",
    "n": 1,
    "size": "1024x1024",
    "output_format": "png",
    "quality": "auto",
    "moderation": "auto",
}, dry_run=True)

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

Manual polling tasks

tasks.get читает task status. tasks.getResponse читает final response. Предпочитайте полные statusUrl и responseUrl, которые возвращает API; используйте endpoint-based URL construction только когда эти URL недоступны.

TypeScript
Python

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

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

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

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

Models и SkillHub

models.list: список доступных моделей по page, type, keywords и provider.
models.getSpec и models.get_spec: читают model contract, используемый для generation planning, включая protocol, body mode, submit endpoint, inputSchema, prerequisites, context inputs, field aliases и input rules, если они есть.
skills.find: поиск в SkillHub по keyword.
skills.list: список SkillHub skills с pagination.

Ошибки

Частые SDK errors:

Error	Сценарий
`AuthError`	API key отсутствует, invalid или unauthorized.
`BalanceError`	Недостаточный баланс.
`ValidationError`	Отсутствует `modelId` / `params`, неподдерживаемый protocol или body mode, либо отсутствуют top-level required fields из model contract.
`ModelNotFoundError`	Модель отсутствует или обязательный model contract не может быть прочитан.
`NetworkError`	HTTP non-2xx или network failure.
`TimeoutError`	Таймаут одного HTTP request.
`TaskTimeoutError`	Таймаут synchronous task wait.

TypeScript и Python callers могут использовать isSeaCloudError(error), чтобы определить SDK errors и прочитать стабильные поля type, message и hint.

Языковые различия

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