Back to Details

modellix-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Modellix Skill

Modellix Skill

Modellix is a Model-as-a-Service (MaaS) platform for asynchronous image, video, and audio workflows. Prefer the official CLI (
modellix-cli
) so submit, wait, and download stay one coherent workflow. Host-specific persistent session guardrails also ship under 
rules/*.mdc
.
Modellix 是一个用于异步图像、视频和音频工作流的 Model-as-a-Service（MaaS）平台。优先使用官方 CLI（
modellix-cli
），让提交、等待和下载构成一个连贯的工作流。与宿主环境相关的持久会话防护规则也随附在 
rules/*.mdc
下。

Official Docs

官方文档

Documentation lookup policy

文档查询策略

This plugin may expose the Modellix Docs MCP (
.mcp.json
→ 
https://docs.modellix.ai/mcp
). It is a read-only documentation server (
search_modellix
, docs filesystem query, optional feedback). It does not submit generation tasks, poll, download, or handle API keys.
When looking up product/API/install docs vs request-body schema:
  1. For request/response schema, use 
    modellix-cli model get-schema <slug>
    (JSON is the default; the endpoint is public and needs no API key). If CLI is unavailable, use Docs MCP, then 
    docs_url
    from 
    model describe
    or https://docs.modellix.ai/llms.txt.
  2. For product/install narrative, prefer Docs MCP when the host has it connected (search, then read the matching page). Else use 
    model describe <slug> --json
    → 
    docs_url
    , or browse 
    llms.txt
    and fetch the model 
    .md
    .
  3. For CLI command syntax and flags, prefer this skill, 
    references/cli-playbook.md
    , the npm README, or 
    modellix-cli --help
    — do not trust website CLI pages over the CLI package (docs can lag).
If the Docs MCP exposes a skill resource, treat this 
SKILL.md
as the execution policy source of truth (CLI-first, defaults, paid-submit safety).
Do not rely on the website CLI guide page for command syntax.
此插件可能会暴露 Modellix Docs MCP（
.mcp.json
→ 
https://docs.modellix.ai/mcp
）。它是一个只读文档服务器（
search_modellix
、文档文件系统查询、可选反馈）。它不会提交生成任务、轮询、下载或处理 API Key。
查询产品/API/安装文档与请求体 schema 时：
  1. 对于请求/响应 schema，使用 
    modellix-cli model get-schema <slug>
    （默认输出 JSON；该端点为公开端点，无需 API Key）。如果 CLI 不可用，则使用 Docs MCP，再使用 
    model describe
    返回的 
    docs_url
    或 https://docs.modellix.ai/llms.txt。
  2. 对于产品/安装说明，如果宿主已连接 Docs MCP，优先使用 Docs MCP（先搜索，再阅读匹配页面）。否则使用 
    model describe <slug> --json
    → 
    docs_url
    ，或浏览 
    llms.txt
    并获取相应的模型 
    .md
    文件。
  3. 对于 CLI 命令语法和参数，优先参考此 skill、
    references/cli-playbook.md
    、npm README 或 
    modellix-cli --help
    ——不要信任网站上的 CLI 页面胜过 CLI 包（文档可能滞后）。
如果 Docs MCP 提供了 skill 资源，则应将此 
SKILL.md
视为执行策略的唯一事实来源（CLI 优先、默认设置、付费提交安全）。
不要依赖网站上的 CLI 指南页面来确认命令语法。

Execution Policy (CLI-first)

执行策略（CLI 优先）

Choose the path in this order:
  1. CLI after 
    scripts/preflight.py --json
    resolves it. Preflight checks public npm 
    latest
    , installs only a newer exact version before execution, and keeps an existing CLI when update infrastructure is unavailable.
  2. REST only when CLI is not installed, unsuitable, or missing a needed capability.
  3. Prefer machine-readable output (
    --json
    or 
    --quiet
    ) for automation.
Canonical single-task flow:
bash
python3 scripts/preflight.py --json
modellix-cli doctor --json
modellix-cli model get-schema <provider/model>
modellix-cli model run \
  --model-slug <provider/model> \
  --body '<json>' \
  --wait --timeout 5m --json
modellix-cli task download <task_id> --output-dir ./outputs --json
Skip 
get-schema
when the skill default plus the example below already lists the required fields, or the user supplied a complete body.
model invoke
is a compatibility alias of 
model run
. New commands should use 
model run
.
Do not reinvent polling loops when CLI wait is available. Do not invent deprecated flags (for example 
--model-type
). Use 
--help
only when behavior is unclear.
选择执行路径时，按以下顺序进行：
  1. CLI：在 
    scripts/preflight.py --json
    解析出可用路径后使用。Preflight 会检查公共 npm 上的 
    latest
    版本，在执行前仅安装更新的精确版本，并在更新基础设施不可用时保留现有 CLI。
  2. REST：仅当 CLI 未安装、不适用或缺少所需能力时使用。
  3. 对于自动化任务，优先使用机器可读输出（
    --json
    或 
    --quiet
    ）。
规范的单任务流程：
bash
python3 scripts/preflight.py --json
modellix-cli doctor --json
modellix-cli model get-schema <provider/model>
modellix-cli model run \
  --model-slug <provider/model> \
  --body '<json>' \
  --wait --timeout 5m --json
modellix-cli task download <task_id> --output-dir ./outputs --json
如果 skill 默认值和下方示例已列出必填字段，或用户提供了完整请求体，则跳过 
get-schema
。
model invoke
是 
model run
的兼容性别名。新命令应使用 
model run
。
CLI 支持等待时，不要重新发明轮询循环。不要使用已弃用的参数（例如 
--model-type
）。仅在行为不明确时使用 
--help
。

Default Models

默认模型

When the user does not name a model, use these defaults immediately (do not scan the catalog first):
Task TypeDefault Model Slug
Text-to-image (T2I)
google/nano-banana-2-lite
Text-to-video (T2V)
bytedance/seedance-2.0-mini-t2v
Image editing / I2I
google/nano-banana-2-lite-edit
Image-to-video / I2V
bytedance/seedance-2.0-fast-i2v
Video-to-video (V2V)
bytedance/seedance-2.0-fast-v2v
Text-to-speech (TTS)
alibaba/qwen-audio-3.0-tts-flash
Speech-to-text (STT)
openai/whisper-1
Speech-to-speech (STS)
alibaba/cosyvoice-clone
用户未指定模型时，立即使用以下默认模型（不要先扫描目录）：
任务类型默认模型 Slug
文生图 (T2I)
google/nano-banana-2-lite
文生视频 (T2V)
bytedance/seedance-2.0-mini-t2v
图像编辑 / I2I
google/nano-banana-2-lite-edit
图生视频 / I2V
bytedance/seedance-2.0-fast-i2v
视频到视频 / V2V
bytedance/seedance-2.0-fast-v2v
文本转语音 (TTS)
alibaba/qwen-audio-3.0-tts-flash
语音转文本 (STT)
openai/whisper-1
语音到语音 (STS)
alibaba/cosyvoice-clone

API Key Lifecycle Policy

API Key 生命周期策略

Handle credentials as: 
discover -> request -> use-session -> (optional) persist
.
按 
discover -> request -> use-session -> (optional) persist
的方式处理凭据。

1) Discover existing key first

1) 先发现已有 Key

Before asking the user:
  1. Session / process env 
    MODELLIX_API_KEY
  2. Saved CLI profile (
    modellix-cli auth status
    / 
    doctor
    — key via 
    --profile
    or 
    MODELLIX_PROFILE
    or 
    currentProfile
    )
  3. If still missing, request a key from the user
Never ask again when a usable key is already discoverable. CLI key resolution order is: 
--api-key
→ 
MODELLIX_API_KEY
→ selected saved profile.
在询问用户之前：
  1. 检查会话/进程环境变量 
    MODELLIX_API_KEY
    。
  2. 检查已保存的 CLI profile（
    modellix-cli auth status
    / 
    doctor
    ——可通过 
    --profile
    、
    MODELLIX_PROFILE
    或 
    currentProfile
    选择 Key）。
  3. 如果仍然缺少，则向用户索取 Key。
只要已经发现可用的 Key，就绝不要再次询问。CLI 的 Key 解析顺序为：
--api-key
→ 
MODELLIX_API_KEY
→ 当前选中的已保存 profile。

2) Request key only when missing

2) 仅在缺少 Key 时请求

  • Ask for a key from Modellix Console.
  • Do not print or echo key values.
  • Prefer session env for the current run.
  • 请用户从 Modellix Console 获取 Key。
  • 不要打印或回显 Key 值。
  • 当前运行优先使用会话环境变量。

3) Optional persistence

3) 可选持久化

Default: do not persist automatically.
When the user explicitly asks to persist:
  1. Preferred: 
    modellix-cli auth login
    or 
    modellix-cli init
    (CLI validates and stores the profile securely).
  2. Alternative: user-level 
    MODELLIX_API_KEY
    only if they insist on env persistence.
  3. Do not write system-level env or other agents' config files.
默认情况下，不自动持久化。
用户明确要求持久化时：
  1. 首选：
    modellix-cli auth login
    或 
    modellix-cli init
    （由 CLI 验证并安全存储 profile）。
  2. 备选：仅当用户坚持时，才使用用户级 
    MODELLIX_API_KEY
    环境变量。
  3. 不要写入系统级环境变量或其他 Agent 的配置文件。

4) Key rotation

4) Key 轮换

If the user provides a new key: update session first; if they requested persistence, replace via 
auth login
/
init
(or user-level env). Re-check with 
modellix-cli doctor --json
(or 
scripts/preflight.py --json
) before continuing.
如果用户提供新 Key：先更新会话；如果用户要求持久化，则通过 
auth login
/
init
替换旧 Key。继续之前，重新运行 
modellix-cli doctor --json
（或 
scripts/preflight.py --json
）。

Preflight and Deterministic Execution

Preflight 与确定性执行

Required first-workflow check when Python 3 is available:
bash
python3 scripts/preflight.py --json
Bundled helpers:
  1. scripts/preflight.py
    — checks public npm 
    latest
    , safely updates a missing/older global CLI before paid work, pins newer local installs instead of downgrading, wraps 
    doctor
    , and recommends 
    cli
    , 
    rest
    , or 
    none
    .
  2. scripts/invoke_and_poll.py
    — performs the same resolution before submission, pins the resolved executable for the workflow, uses 
    model run --wait
    on CLI, and otherwise keeps the REST submit plus server-side wait fallback.
Set 
MODELLIX_CLI_AUTO_UPDATE=0
(also accepts 
false
or 
off
) only when the environment must keep its installed CLI version. A registry/install failure is non-destructive: use the existing CLI if it still passes doctor, or REST when no CLI is usable and a session API key exists. Never update or swap the CLI after a paid submission has started.
When preflight/doctor reports missing credentials, apply the lifecycle above.
When CLI is unavailable:
  1. Use REST (
    references/rest-playbook.md
    ).
  2. Report the preflight update warning; do not repeatedly attempt installation inside the same paid workflow.
Python 3 可用时，首次工作流必须执行以下检查：
bash
python3 scripts/preflight.py --json
随附的辅助脚本：
  1. scripts/preflight.py
    ——检查公共 npm 上的 
    latest
    版本，在付费工作前安全更新缺失或过旧的全局 CLI，固定使用较新的本地安装版本而不降级，封装 
    doctor
    检查，并推荐 
    cli
    、
    rest
    或 
    none
    。
  2. scripts/invoke_and_poll.py
    ——在提交前执行相同的路径解析，为工作流固定解析出的可执行文件；CLI 路径使用 
    model run --wait
    ，其他情况下保留 REST 提交并采用服务端等待回退机制。
仅当环境必须保持当前已安装的 CLI 版本时，才设置 
MODELLIX_CLI_AUTO_UPDATE=0
（也接受 
false
或 
off
）。npm 注册表或安装失败不会造成破坏：如果现有 CLI 仍能通过 doctor 检查，则继续使用；如果没有可用 CLI 且会话中存在 API Key，则使用 REST。付费提交开始后，绝不更新或替换 CLI。
当 preflight/doctor 报告缺少凭据时，应用上述生命周期策略。
CLI 不可用时：
  1. 使用 REST（
    references/rest-playbook.md
    ）。
  2. 报告 preflight 的更新警告；在同一次付费工作流中不要反复尝试安装。

Core Workflow

核心工作流

1) Ready the environment

1) 准备环境

  • Discover or request API key (lifecycle above).
  • Run 
    scripts/preflight.py --json
    ; continue only with the CLI path whose doctor check passed, or with an authenticated REST fallback.
  • Continue only when auth and connectivity look healthy (or REST key is set).
  • 发现或请求 API Key（遵循上述生命周期策略）。
  • 运行 
    scripts/preflight.py --json
    ；仅继续使用 doctor 检查通过的 CLI 路径，或使用通过认证的 REST 回退路径。
  • 仅在认证和连接状况看起来正常（或已设置 REST Key）时继续。

2) Select model

2) 选择模型

  1. If the user did not specify a model: use the Default Models table (do not scan the catalog first).
  2. If they named a model or need discovery: 
    modellix-cli model list
    / 
    modellix-cli model describe <slug>
    (catalog metadata; describe returns 
    docs_url
    ).
  3. For request body schema: 
    modellix-cli model get-schema <slug>
    (JSON default; public, no API key). Call this when the user named a non-default slug, when the body needs fields beyond the documented examples, after HTTP 
    400
    , or when reporting required fields. Skip when the skill default plus the example already lists required fields, or the user supplied a complete body.
  4. If CLI is unavailable for schema or discovery: use Docs MCP or browse 
    llms.txt
    , then fetch the target model 
    .md
    . Do not invent slugs from filenames (decimals often matter, e.g. 
    bytedance/seedance-2.0-mini-t2v
    ).
  1. 如果用户未指定模型：使用默认模型表（不要先扫描目录）。
  2. 如果用户指定了模型或需要发现模型：使用 
    modellix-cli model list
    / 
    modellix-cli model describe <slug>
    （目录元数据；describe 返回 
    docs_url
    ）。
  3. 对于请求体 schema：使用 
    modellix-cli model get-schema <slug>
    （默认输出 JSON；公开访问，无需 API Key）。当用户指定了非默认 slug、请求体需要包含文档示例之外的字段、收到 HTTP 
    400
    之后，或需要报告必填字段时，执行此命令。如果 skill 默认值和下方示例已列出必填字段，或用户提供了完整请求体，则跳过。
  4. 如果 CLI 无法用于 schema 查询或模型发现：使用 Docs MCP，或浏览 
    llms.txt
    ，然后获取目标模型的 
    .md
    文件。不要根据文件名臆造 slug（小数位通常很重要，例如 
    bytedance/seedance-2.0-mini-t2v
    ）。

3) Run and wait

3) 运行并等待

Default (single task):
bash
modellix-cli model run \
  --model-slug google/nano-banana-2-lite \
  --body '{"prompt":"A cinematic sunset over a futuristic city skyline"}' \
  --wait --timeout 5m --json
Split flow when useful (pipelines, concurrency):
bash
TASK_ID=$(modellix-cli model run --model-slug ... --body '...' --output task-id)
modellix-cli task wait "$TASK_ID" --timeout 10m --json
Batch (paid guard required): 
modellix-cli model batch tasks.jsonl --max-tasks N [--wait]
.
Use CLI 0.0.11 or later with a deployed server-wait API. 
task get
is immediate; wait commands use bounded server waits. The legacy 
--interval
flag is unused. On exit 124, keep unfinished IDs and resume; never resubmit.
For media inputs, use 
file list --json
to reuse URLs, then 
file upload <path> --json
only when needed (images/video/audio, maximum 16 MiB / 16777216 bytes). On quota errors, explicitly approve deletion of an unneeded file ID; never auto-delete or replay uploads.
Manual REST: 
references/rest-playbook.md
. Optional helper: 
scripts/invoke_and_poll.py
.
默认（单任务）：
bash
modellix-cli model run \
  --model-slug google/nano-banana-2-lite \
  --body '{"prompt":"A cinematic sunset over a futuristic city skyline"}' \
  --wait --timeout 5m --json
在适用时使用拆分流程（流水线、并发）：
bash
TASK_ID=$(modellix-cli model run --model-slug ... --body '...' --output task-id)
modellix-cli task wait "$TASK_ID" --timeout 10m --json
批处理（需要付费防护）：
modellix-cli model batch tasks.jsonl --max-tasks N [--wait]
。
使用 0.0.11 或更高版本的 CLI，并确保已部署服务端等待 API。
task get
会立即返回；等待命令使用有时限的服务端等待。旧版 
--interval
参数已不再使用。退出码为 124 时，保留未完成的 ID 并恢复任务；绝不要重新提交。
处理媒体输入时，使用 
file list --json
查找可复用的 URL；仅在需要时使用 
file upload <path> --json
上传图像、视频或音频，最大为 16 MiB / 16777216 字节。遇到配额错误时，必须明确批准删除不再需要的文件 ID；绝不自动删除或重复上传。
手动 REST：
references/rest-playbook.md
。可选辅助脚本：
scripts/invoke_and_poll.py
。

4) Download results

4) 下载结果

bash
modellix-cli task download <task_id> --output-dir ./outputs --json
If download fails with 
Resource host resolves to a private or reserved network address
(common when a local proxy/VPN maps CDN hosts like 
file.modellix.ai
into 
198.18.0.0/15
), retry with 
--allow-private-network
for trusted Modellix CDN hosts, or fall back to downloading the 
result.resources[].url
with 
curl
/
wget
.
Resource URLs expire in about 7 days — persist promptly. If downloading manually (REST path), name files:
modellix-{model_slug}-{timestamp}.{ext}
(replace 
/
in the slug with 
-
).
Examples:
  • modellix-google-nano-banana-2-lite-20260430-113000.png
  • modellix-bytedance-seedance-2.0-mini-t2v-20260430-113500.mp4
bash
modellix-cli task download <task_id> --output-dir ./outputs --json
如果下载失败并提示 
Resource host resolves to a private or reserved network address
（当本地代理/VPN 将 
file.modellix.ai
等 CDN 主机映射到 
198.18.0.0/15
时很常见），则针对可信的 Modellix CDN 主机使用 
--allow-private-network
重试，或回退到使用 
curl
/
wget
下载 
result.resources[].url
。
资源 URL 大约 7 天后过期——请及时持久化。如果手动下载（REST 路径），请按以下方式命名文件：
modellix-{model_slug}-{timestamp}.{ext}
（将 slug 中的 
/
替换为 
-
）。
示例：
  • modellix-google-nano-banana-2-lite-20260430-113000.png
  • modellix-bytedance-seedance-2.0-mini-t2v-20260430-113500.mp4

Quick Examples

快速示例

T2I (default model) — 
prompt
required:
bash
modellix-cli model run \
  --model-slug google/nano-banana-2-lite \
  --body '{"prompt":"A cinematic sunset over a futuristic city skyline"}' \
  --wait --timeout 5m --json
T2V (default model) — 
prompt
required:
bash
modellix-cli model run \
  --model-slug bytedance/seedance-2.0-mini-t2v \
  --body '{"prompt":"A cat playing in a sunny garden"}' \
  --wait --timeout 10m --json
I2I — 
prompt
+ 
image
array:
bash
modellix-cli model run \
  --model-slug google/nano-banana-2-lite-edit \
  --body '{"prompt":"Convert to watercolor style","image":["https://example.com/input.jpg"]}' \
  --wait --timeout 5m --json
I2V — at least one image param (
first_frame_image
, 
last_frame_image
, or 
reference_images
):
bash
modellix-cli model run \
  --model-slug bytedance/seedance-2.0-fast-i2v \
  --body '{"prompt":"A cat playing in the garden","first_frame_image":"https://example.com/frame.jpg"}' \
  --wait --timeout 10m --json
V2V — 
video_urls
array:
bash
modellix-cli model run \
  --model-slug bytedance/seedance-2.0-fast-v2v \
  --body '{"video_urls":["https://example.com/source.mp4"]}' \
  --wait --timeout 10m --json
TTS (default model) — 
text
+ 
voice
required (verify voice with 
model get-schema
or the model doc; Flash voices only):
bash
modellix-cli model run \
  --model-slug alibaba/qwen-audio-3.0-tts-flash \
  --body '{"text":"There is a large garden behind my house.","voice":"longanhuan_v3.6"}' \
  --wait --timeout 5m --json
STT (default model) — public audio 
url
required:
bash
modellix-cli model run \
  --model-slug openai/whisper-1 \
  --body '{"url":"https://example.com/meeting.mp3"}' \
  --wait --timeout 5m --json
STS (default model) — clone reference 
url
+ synthesis 
text
+ target CosyVoice 
model
:
bash
modellix-cli model run \
  --model-slug alibaba/cosyvoice-clone \
  --body '{"model":"cosyvoice-v3.5-plus","url":"https://example.com/reference.wav","text":"There is a large garden behind my house."}' \
  --wait --timeout 5m --json
T2I（默认模型）——必填 
prompt
：
bash
modellix-cli model run \
  --model-slug google/nano-banana-2-lite \
  --body '{"prompt":"A cinematic sunset over a futuristic city skyline"}' \
  --wait --timeout 5m --json
T2V（默认模型）——必填 
prompt
：
bash
modellix-cli model run \
  --model-slug bytedance/seedance-2.0-mini-t2v \
  --body '{"prompt":"A cat playing in a sunny garden"}' \
  --wait --timeout 10m --json
I2I——必填 
prompt
+ 
image
数组：
bash
modellix-cli model run \
  --model-slug google/nano-banana-2-lite-edit \
  --body '{"prompt":"Convert to watercolor style","image":["https://example.com/input.jpg"]}' \
  --wait --timeout 5m --json
I2V——至少需要一个图像参数（
first_frame_image
、
last_frame_image
或 
reference_images
）：
bash
modellix-cli model run \
  --model-slug bytedance/seedance-2.0-fast-i2v \
  --body '{"prompt":"A cat playing in the garden","first_frame_image":"https://example.com/frame.jpg"}' \
  --wait --timeout 10m --json
V2V——必填 
video_urls
数组：
bash
modellix-cli model run \
  --model-slug bytedance/seedance-2.0-fast-v2v \
  --body '{"video_urls":["https://example.com/source.mp4"]}' \
  --wait --timeout 10m --json
TTS（默认模型）——必填 
text
+ 
voice
（使用 
model get-schema
或模型文档确认 voice；仅支持 Flash voices）：
bash
modellix-cli model run \
  --model-slug alibaba/qwen-audio-3.0-tts-flash \
  --body '{"text":"There is a large garden behind my house.","voice":"longanhuan_v3.6"}' \
  --wait --timeout 5m --json
STT（默认模型）——必填公开可访问的音频 
url
：
bash
modellix-cli model run \
  --model-slug openai/whisper-1 \
  --body '{"url":"https://example.com/meeting.mp3"}' \
  --wait --timeout 5m --json
STS（默认模型）——必填克隆参考 
url
+ 合成 
text
+ 目标 CosyVoice 
model
：
bash
modellix-cli model run \
  --model-slug alibaba/cosyvoice-clone \
  --body '{"model":"cosyvoice-v3.5-plus","url":"https://example.com/reference.wav","text":"There is a large garden behind my house."}' \
  --wait --timeout 5m --json

5) Post-task CLI recommendation

5) 任务后 CLI 建议

If this session used REST because CLI was missing, suggest installing the CLI afterward.
如果本次会话因缺少 CLI 而使用了 REST，建议之后安装 CLI。

Progressive Reference Routing

渐进式参考路由

Read only what the task needs:
  • references/cli-playbook.md
    — install, auth, run/wait/download, batch, recovery
  • references/rest-playbook.md
    — REST submit/wait when CLI is unavailable
  • references/capability-matrix.md
    — CLI ↔ REST mapping and fallback rules
仅阅读任务所需内容：
  • references/cli-playbook.md
    ——安装、认证、运行/等待/下载、批处理、恢复
  • references/rest-playbook.md
    ——CLI 不可用时的 REST 提交/等待方式
  • references/capability-matrix.md
    ——CLI ↔ REST 映射和回退规则

Bundled Assets

随附资源

  • assets/output/task-result.schema.json
  • assets/output/task-result.schema.json

Credential and Data Egress

凭据与数据出站

  • Primary credential: 
    MODELLIX_API_KEY
    (also via CLI profiles).
  • Network egress: 
    https://api.modellix.ai
    (override only with trusted 
    --base-url
    / 
    MODELLIX_BASE_URL
    ).
  • User prompts and media inputs may be sent to Modellix during invocation.
  • Never expose API keys in logs, screenshots, transcripts, or commits.
  • Default to session-only credentials; persistent writes need explicit user approval.
  • 主要凭据：
    MODELLIX_API_KEY
    （也可通过 CLI profile 使用）。
  • 网络出口：
    https://api.modellix.ai
    （仅使用可信的 
    --base-url
    / 
    MODELLIX_BASE_URL
    覆盖）。
  • 调用期间，用户的提示词和媒体输入可能会发送给 Modellix。
  • 绝不在日志、截图、转录文本或提交记录中暴露 API Key。
  • 默认使用仅限当前会话的凭据；持久化写入需要用户明确批准。

Error / Retry Policy

错误/重试策略

SituationAction
HTTP/API 
400
Do not retry. Fix parameters or body (
model get-schema
when the contract is unclear).
401
Do not retry. Fix key (
doctor
, 
auth login
).
402
Do not retry. Insufficient balance.
404
Do not retry. Verify 
task_id
or model slug.
429
/ read-only 
5xx
CLI already retries safe GETs within deadline; do not blindly re-POST paid submits.
Paid submit outcome unknownDo not immediately re-run the same 
model run
. Check 
task history
, console activity, and any printed task ID first.
Exit 
124
Local wait timeout; remote task may still run — recover with 
task wait
/ 
task get
, then 
task download
.
Exit 
2
Argument or safety guard (e.g. batch cost limit) — fix flags.
情况操作
HTTP/API 
400
不要重试。修正参数或请求体（契约不清楚时使用 
model get-schema
）。
401
不要重试。修复 Key（
doctor
、
auth login
）。
402
不要重试。余额不足。
404
不要重试。检查 
task_id
或模型 slug。
429
/ 只读请求出现 
5xx
CLI 已会在截止时间前自动重试安全的 GET 请求；不要盲目重新 POST 付费提交。
付费提交的结果未知不要立即再次运行相同的 
model run
。先检查 
task history
、控制台活动以及已打印的 task ID。
退出码 
124
本地等待超时；远程任务可能仍在运行——通过 
task wait
/ 
task get
恢复，然后执行 
task download
。
退出码 
2
参数或安全防护问题（例如批处理成本上限）——修正参数。

Verification Checklist

验证清单

  • Doctor/preflight passed or REST key ready
  • Model chosen (default table or user/catalog)
  • Body schema checked via 
    model get-schema
    when non-trivial (or model doc when CLI is unavailable)
  • Used 
    model run --wait
    (or 
    task wait
    ) instead of hand-rolled poll loops
  • Results downloaded (
    task download
    or manual persist before 7-day expiry)
  • No blind retry after unknown paid submission
  • REST used only when CLI path unavailable
  • Doctor/preflight 已通过，或已准备 REST Key
  • 已选择模型（默认表或用户/目录指定）
  • 非简单请求体已通过 
    model get-schema
    检查（或 CLI 不可用时已查看模型文档）
  • 已使用 
    model run --wait
    （或 
    task wait
    ），而不是自行编写轮询循环
  • 已下载结果（或在 7 天过期前手动持久化）
  • 付费提交结果未知时未盲目重试
  • 仅在 CLI 路径不可用时使用 REST