modellix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Modellix Skill

Modellix is a Model-as-a-Service (MaaS) platform with async image/video generation APIs. The invariant flow is: submit task -> get

task_id

-> poll until

success

failed

Modellix是一个提供异步图像/视频生成API的Model-as-a-Service（MaaS）平台。固定流程为：提交任务 -> 获取

task_id

-> 轮询直到状态变为

success

或

failed

。

Execution Policy (CLI-first)

执行策略（优先使用CLI）

Always choose execution path in this order:

Use CLI when
```
modellix-cli
```
is available and authenticated.
Fall back to REST when CLI is unavailable, unsuitable, or missing capability.
Prefer machine-readable outputs (
```
--json
```
) in CLI flows.

For CLI mode, use these two commands as the default command set:

Create task:

modellix-cli model invoke --model-slug <provider/model> --body|--body-file ...

Get result:
```
modellix-cli task get <task_id>
```

Do not guess or invent deprecated flags (for example

--model-type

). Use

--help

only as an assistive fallback when command behavior is unclear.

请始终按照以下顺序选择执行路径：

当
```
modellix-cli
```
可用且已完成认证时，使用CLI。
当CLI不可用、不适用或缺少对应功能时，回退到REST方式。
在CLI流程中优先使用机器可读输出格式（
```
--json
```
）。

对于CLI模式，默认使用以下两组命令：

创建任务：

modellix-cli model invoke --model-slug <provider/model> --body|--body-file ...

获取结果：
```
modellix-cli task get <task_id>
```

请勿猜测或使用已废弃的参数（例如

--model-type

）。仅当命令行为不明确时，才将

--help

作为辅助回退方式。

API Key Lifecycle Policy

API密钥生命周期策略

Always handle

MODELLIX_API_KEY

with this lifecycle:

discover -> request -> use-session -> (optional) persist-user-env

请始终按照以下生命周期处理

MODELLIX_API_KEY

：

发现 -> 请求 -> 会话内使用 ->（可选）持久化到用户环境

。

1) Discover existing key first

1) 优先发现现有密钥

Before asking the user for credentials, check in this order:

Current session environment variable
```
MODELLIX_API_KEY
```
.
Existing user-level environment variable
```
MODELLIX_API_KEY
```
if already configured.
If both are unavailable, treat as first-use and request key from user.

Never ask for a key again when a valid key is already discoverable.

在向用户请求凭证之前，请按以下顺序检查：

当前会话环境变量
```
MODELLIX_API_KEY
```
。
已配置的用户级环境变量
```
MODELLIX_API_KEY
```
。
如果两者均不可用，则视为首次使用，向用户请求密钥。

当可发现有效密钥时，切勿再次向用户请求密钥。

2) Request key only when missing

2) 仅在缺失时请求密钥

If no usable key is found:

Ask user to provide a Modellix API key.
Do not print or echo key values in logs/output.
Use the key for current authentication flow in session scope by default.

如果未找到可用密钥：

请求用户提供Modellix API密钥。
请勿在日志/输出中打印或回显密钥值。
默认在会话范围内使用该密钥完成当前认证流程。

3) Optional persistence for future sessions

3) 可选的跨会话持久化

Default behavior: do not persist automatically.

If and only if the user explicitly asks for persistence, write to user-level environment settings:

Preferred and allowed persistent target: user-level
```
MODELLIX_API_KEY
```
.
Do not write system-level environment variables by default.
Do not write credentials into other coding agents' local config files.

默认行为：不自动持久化。

仅当用户明确要求持久化时，才写入用户级环境设置：

首选且允许的持久化目标：用户级
```
MODELLIX_API_KEY
```
。
默认不写入系统级环境变量。
请勿将凭证写入其他编码Agent的本地配置文件。

4) Replace key when user provides a new one

4) 用户提供新密钥时进行替换

If the user provides a new API key, treat it as a key rotation event:

Replace current session value first.
Only if the user explicitly requested persistence, also replace the user-level env value.
Do not keep old and new keys active in parallel in this skill workflow.
Re-run
```
scripts/preflight.py --json
```
after replacement and continue only if the new key is valid.

When replacement fails validation, keep the flow blocked, report the validation failure, and request a corrected key.

如果用户提供新的API密钥，则将其视为密钥轮换事件：

首先替换当前会话中的密钥值。
仅当用户明确要求持久化时，才同时替换用户级环境变量中的值。
在此Skill工作流中，请勿同时保留旧密钥和新密钥处于活跃状态。
替换后重新运行
```
scripts/preflight.py --json
```
，仅当新密钥验证通过后才继续流程。

如果替换后验证失败，请暂停流程，报告验证失败，并请求用户提供正确的密钥。

Preflight and Deterministic Execution

预检与确定性执行

Default execution path is the CLI command pair (

model invoke

task get

Bundled scripts are optional helpers for automation:

```
scripts/preflight.py
```
- Validates CLI availability and API key presence.
- Returns recommended mode (
```
cli
```
  or
```
rest
```
  ).
```
scripts/invoke_and_poll.py
```
- Executes CLI-first with REST fallback support.
- Handles exponential backoff polling and retryable submit errors.
- Emits normalized JSON result output.

When preflight reports missing credentials, apply the lifecycle policy above:

Try discover flow (session env -> existing user env).
Request key from user only if still missing.
Use session value and retry.
Persist only when explicitly requested by the user.

When preflight reports

cli_available=false

Offer optional CLI install (
```
npm i -g modellix-cli
```
) and ask user consent first.
If user declines or install fails, continue with REST fallback (supported path).

Quick commands:

powershell

python scripts/preflight.py --json
python scripts/invoke_and_poll.py --model-slug bytedance/seedream-4.5-t2i --body '{"prompt":"A cinematic portrait of a fox in a misty forest at sunrise"}'

默认执行路径为CLI命令组合（

model invoke

task get

）。

捆绑脚本是可选的自动化辅助工具：

```
scripts/preflight.py
```
- 验证CLI可用性和API密钥是否存在。
- 返回推荐模式（
```
cli
```
  或
```
rest
```
  ）。
```
scripts/invoke_and_poll.py
```
- 优先执行CLI，支持REST回退。
- 处理指数退避轮询和可重试的提交错误。
- 输出标准化JSON结果。

当预检报告凭证缺失时，请应用上述生命周期策略：

尝试发现流程（会话环境 -> 现有用户环境）。
仅当仍缺失时，向用户请求密钥。
使用会话内密钥并重试。
仅在用户明确同意时进行持久化。

当预检报告

cli_available=false

时：

提供可选的CLI安装（
```
npm i -g modellix-cli
```
），并先征得用户同意。
如果用户拒绝或安装失败，则继续使用REST回退（支持路径）。

快速命令示例：

powershell

python scripts/preflight.py --json
python scripts/invoke_and_poll.py --model-slug bytedance/seedream-4.5-t2i --body '{"prompt":"A cinematic portrait of a fox in a misty forest at sunrise"}'

Core Workflow

核心工作流

1) Discover or request API key

1) 发现或请求API密钥

Run key discovery first (session env, then existing user-level env).
If not found, ask user for key created in Modellix Console.
Use key in session scope by default (no automatic persistence).
Persist only on explicit user consent:
- Allowed persistent target: user-level
```
MODELLIX_API_KEY
```
  .
- Not allowed by default: system-level env writes or other agent config writes.
If user provides a new key later, replace the existing stored key and re-run preflight validation.
Retry preflight and continue only after key is discoverable.

优先执行密钥发现流程（会话环境，然后是现有用户级环境）。
如果未找到，请向用户请求在Modellix控制台创建的密钥。
默认在会话范围内使用密钥（不自动持久化）。
仅在用户明确同意时进行持久化：
- 允许的持久化目标：用户级
```
MODELLIX_API_KEY
```
  。
- 默认不允许：写入系统级环境变量或其他Agent配置文件。
如果用户后续提供新密钥，请替换已存储的现有密钥并重新运行预检验证。
仅当密钥可被发现时，才重新运行预检并继续流程。

2) Select model

2) 选择模型

Read

references/REFERENCE.md

to find model docs and parameters.

阅读

references/REFERENCE.md

以查找模型文档和参数。

3) Run invocation and poll

3) 调用模型并轮询结果

Preferred default: CLI command pair from

references/cli-playbook.md

```
modellix-cli model invoke ...
```
```
modellix-cli task get <task_id>
```

Manual REST flow:
```
references/rest-playbook.md
```
Optional helper:
```
scripts/invoke_and_poll.py
```
for auto polling/normalized output

首选默认方式：

references/cli-playbook.md

中的CLI命令组合

```
modellix-cli model invoke ...
```
```
modellix-cli task get <task_id>
```

手动REST流程：
```
references/rest-playbook.md
```
可选辅助工具：
```
scripts/invoke_and_poll.py
```
，用于自动轮询/标准化输出

4) Consume resources

4) 存储资源

Output media URLs are under

result.resources

. Persist assets promptly; results expire in 24 hours.

输出媒体URL位于

result.resources

下。请及时持久化资产；结果将在24小时后过期。

Progressive Reference Routing

渐进式参考路由

Read only what the task needs:

```
references/cli-playbook.md
```
- CLI install/auth/command flow and retry guidance
```
references/rest-playbook.md
```
- REST endpoints, headers, status model, retry policy
```
references/capability-matrix.md
```
- CLI command <-> REST endpoint mapping and fallback rules

仅阅读任务所需的内容：

```
references/cli-playbook.md
```
- CLI安装/认证/命令流程及重试指南
```
references/rest-playbook.md
```
- REST端点、请求头、状态模型、重试策略
```
references/capability-matrix.md
```
- CLI命令与REST端点的映射关系及回退规则

Bundled Assets

捆绑资产

Output schema:
- ```
assets/output/task-result.schema.json
```

输出 schema：
- ```
assets/output/task-result.schema.json
```

Credential and Data Egress

凭证与数据流出

Primary credential:
```
MODELLIX_API_KEY
```
.
Required env vars:
```
MODELLIX_API_KEY
```
.
This skill does not require any other secret.
Network egress: sends requests to
```
https://api.modellix.ai
```
.
User payload handling: prompts and user-provided inputs (including media URLs or file-derived content) may be sent to Modellix endpoints during invocation.
Result handling: generated resource URLs come from Modellix response payloads and should be downloaded before expiry (about 24 hours).
Secret hygiene:
- Never expose API keys in terminal output, logs, screenshots, transcripts, or commit content.
- Mask sensitive values when showing command examples.
- Default to session-only credential usage.
- Any persistent write requires explicit user approval and must be user-level env only.
- Do not write system-level env or other agent config files as part of this skill.

主要凭证：
```
MODELLIX_API_KEY
```
。
必填环境变量：
```
MODELLIX_API_KEY
```
。
此Skill不需要其他任何密钥。
网络流出：向
```
https://api.modellix.ai
```
发送请求。
用户负载处理：调用过程中，提示词和用户提供的输入（包括媒体URL或文件衍生内容）可能会发送到Modellix端点。
结果处理：生成的资源URL来自Modellix响应负载，请在过期前（约24小时）下载。
密钥安全规范：
- 切勿在终端输出、日志、截图、对话记录或提交内容中暴露API密钥。
- 展示命令示例时，需屏蔽敏感值。
- 默认仅在会话内使用凭证。
- 任何持久化写入都需要用户明确批准，且只能写入用户级环境变量。
- 作为此Skill的一部分，请勿写入系统级环境变量或其他Agent配置文件。

Error/Retry Policy

错误/重试策略

Unified non-success codes:

Non-retryable:
```
400
```
,
```
401
```
,
```
402
```
,
```
404
```
Retryable:
```
429
```
,
```
500
```
,
```
503
```

Retry behavior:

Exponential backoff (
```
1s -> 2s -> 4s
```
, capped)
For
```
500
```
/
```
503
```
, max 3 retries
For
```
429
```
, respect
```
X-RateLimit-Reset
```
if present

统一非成功状态码：

不可重试：
```
400
```
,
```
401
```
,
```
402
```
,
```
404
```
可重试：
```
429
```
,
```
500
```
,
```
503
```

重试行为：

指数退避（
```
1s -> 2s -> 4s
```
，设上限）
对于
```
500
```
/
```
503
```
，最多重试3次
对于
```
429
```
，如果存在
```
X-RateLimit-Reset
```
则遵循该值

Verification Checklist

验证检查清单

Preflight executed and mode selected (
```
cli
```
or
```
rest
```
)
API key configured (
```
MODELLIX_API_KEY
```
or CLI
```
--api-key
```
)
Model parameters verified against model doc from
```
references/REFERENCE.md
```
Task submit returns
```
task_id
```
with success code
Polling handles
```
pending
```
,
```
processing
```
,
```
success
```
,
```
failed
```
Retry behavior implemented for
```
429/500/503
```
Result URLs persisted before 24-hour expiration
REST fallback validated when CLI path is unavailable

已执行预检并选择模式（
```
cli
```
或
```
rest
```
）
已配置API密钥（
```
MODELLIX_API_KEY
```
或CLI参数
```
--api-key
```
）
已对照
```
references/REFERENCE.md
```
中的模型文档验证模型参数
任务提交成功返回
```
task_id
```
轮询已处理
```
pending
```
,
```
processing
```
,
```
success
```
,
```
failed
```
状态
已为
```
429/500/503
```
状态实现重试行为
已在24小时过期前持久化结果URL
当CLI路径不可用时，已验证REST回退功能

Official Docs

官方文档

API: https://docs.modellix.ai/ways-to-use/api
CLI: https://docs.modellix.ai/ways-to-use/cli
Pricing: https://docs.modellix.ai/get-started/pricing
Full docs index: https://docs.modellix.ai/llms.txt

API：https://docs.modellix.ai/ways-to-use/api
CLI：https://docs.modellix.ai/ways-to-use/cli
定价：https://docs.modellix.ai/get-started/pricing
完整文档索引：https://docs.modellix.ai/llms.txt