scenario

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scenario

Overview

概述

Scenario (scenario.com) generates AI images, video, 3D, and audio across 500+ models plus custom training, all through the core loop below.

Scenario (scenario.com) 通过以下核心循环，在 500+ 模型及自定义训练基础上生成 AI 图像、视频、3D 和音频。

Setup

配置

Endpoint:

https://mcp.scenario.com/mcp

(Streamable HTTP). Prefer OAuth: no credentials pass through the conversation. Client config, API-key setup for headless use, and per-client re-authentication: references/setup.md. Never ask an agent to collect, encode, or echo a secret. A connection that authenticated once and fails later is re-authenticated per client before anything else is debugged: a server-side authentication fix lands only through a fresh handshake, and

diagnostics_run

names the failing layer (

auth

tenant-scope

api-unreachable

, or

healthy

) with trace ids for support.

The default toolset is wider than the core loop below:

asset_get

job_get

jobs_list

and

models_list

are in it too and are called directly, so treat the table as the loop rather than the whole list.

?toolsets=full

exposes everything. The catalog tools are the ones outside it (collections, tagging, analysis, training, members, keys):

scenario_tools_search

with the tool name or plain keywords as

query

(it takes only

query

and

limit

) returns the schema and lane, and the matching

scenario_tool_execute_read

write

delete

runs it with

{name, parameters}

, scope ids inside

parameters

when the target's

inputSchema

declares them, which nearly every catalog tool does (

plan_generation

, which takes only

description

, is the exception), unlike a direct tool's top-level

team_id

project_id

. The lane is the result's own

permission

, not what the verb sounds like:

asset_download

and

asset_analyze

are both write-class.

Endpoint:

https://mcp.scenario.com/mcp

(Streamable HTTP)。优先使用 OAuth：对话中不传递凭据。客户端配置、用于无头使用的 API-key 设置，以及每个客户端的重新认证：references/setup.md。绝不要要求 agent 收集、编码或回显密钥。一个曾经认证成功但之后失败的连接，在调试其他任何问题之前，应先按客户端重新认证：服务端身份验证修复只能通过新的握手完成，

diagnostics_run

会指出失败层（

auth

、

tenant-scope

、

api-unreachable

或

healthy

）并提供 trace id 以供支持。

默认工具集比下面的核心循环更广：

asset_get

、

job_get

、

jobs_list

和

models_list

也包含在内，可直接调用，因此请把表格视作循环而非完整列表。

?toolsets=full

暴露全部工具。目录工具（catalog tools）是核心循环之外的工具（collections、tagging、analysis、training、members、keys）：使用

scenario_tools_search

，以工具名或纯关键字作为

query

（它只接受

query

和

limit

），返回 schema 和 lane；匹配的

scenario_tool_execute_read

write

delete

以

{name, parameters}

运行它，当目标的

inputSchema

声明了 scope id 时，将 scope id 放在

parameters

内——几乎所有目录工具都如此（

plan_generation

是例外，它只接受

description

），这与直接工具顶层的

team_id

project_id

不同。lane 是结果自身的

permission

，而不是动词听起来的样子：

asset_download

和

asset_analyze

都属于 write 类别。

Scope first

先确定 scope

Resolve scope first, then pass

team_id

and

project_id

on every later call.

teams_list

returns the teams with their projects;

projects_list

requires a

team_id

, so it cannot come first. Confirm the pair with the user: a guess writes into someone else's project. A non-interactive run takes the pair from its task instructions; when they name none, stop and list the choices.

The server fills scope in only for read-only tools with one candidate remaining; anything else fails rather than guesses, and the error names which half is wrong (see Errors and recovery). Scope errors are the most common failure here, surfacing mid-session on the first call that drops the pair once a second team or project is in play.

先解析 scope，然后在之后每次调用中传递

team_id

和

project_id

。

teams_list

返回带项目的团队；

projects_list

需要

team_id

，所以不能最先调用。与用户确认这一对 id：猜错会写入别人的项目。非交互式运行从任务指令中获取这一对 id；当指令未指定时，停止并列出可选项。

服务器只会在只读工具且仅剩一个候选时自动填充 scope；其他情况宁可失败也不猜测，错误会指出哪一半是错误的（参见“错误与恢复”）。Scope 错误是这里最常见的失败，通常会在会话中途、当出现第二个团队或项目后第一次调用丢失这一对 id 时浮现。

Quick reference

快速参考

Step	Tool	Notes
Resolve scope	`teams_list` , then `projects_list`	Once per session; pass the ids on every call
Find a model	`search` or `recommend`	Free; `recommend` for a capability, `search` for a name
Get the schema	`model_schema_get`	Always before `model_run` ; check `runs_as` and caps
Generate	`model_run`	Schema-conformant `parameters` ; `dry_run` for cost
Wait	`jobs_wait`	Whenever `model_run` returns a `job_id` without assets; never loop `job_get`
View / save	`asset_display` / `asset_download`	Never paste raw asset URLs; `format` converts images only
Inspect an asset	`asset_get`	Free; dimensions, duration, `firstFrame` / `lastFrame` ids
Upload inputs	`upload_asset` + `upload_asset_complete`	Local files become asset_ids
Refine a prompt	`prompt_spark`	Advisory rewrite; needs `model_id`
Quota / debugging	`usage` , `diagnostics_run`	CU consumption; `diagnose` MCP prompt

A multi-step request ("product video with voiceover", "concept to 3D") goes to

plan_generation

(catalog-only, read lane): plain words in

description

, ordered steps out, each naming a tool and optional model hint; it runs nothing. Single-step:

recommend

步骤	工具	说明
解析 scope	`teams_list` ，然后 `projects_list`	每个会话一次；每次调用传递这些 id
查找模型	`search` 或 `recommend`	免费； `recommend` 按能力， `search` 按名称
获取 schema	`model_schema_get`	在 `model_run` 之前必须调用；检查 `runs_as` 和上限
生成	`model_run`	符合 schema 的 `parameters` ； `dry_run` 用于查看成本
等待	`jobs_wait`	只要 `model_run` 返回 `job_id` 且没有资产时使用；绝不要循环调用 `job_get`
查看 / 保存	`asset_display` / `asset_download`	绝不要粘贴原始资产 URL； `format` 仅转换图像
检查资产	`asset_get`	免费；尺寸、时长、 `firstFrame` / `lastFrame` id
上传输入	`upload_asset` + `upload_asset_complete`	本地文件变成 asset_ids
优化提示词	`prompt_spark`	建议性改写；需要 `model_id`
配额 / 调试	`usage` 、 `diagnostics_run`	CU 消耗； `diagnose` MCP 提示

多步骤请求（“带配音的产品视频”、“概念到 3D”）应交给

plan_generation

（仅目录工具，read lane）：在

description

中用自然语言描述，输出为有序步骤，每一步指定一个工具和可选的模型提示；它不运行任何东西。单步骤：使用

recommend

。

Worked example

完整示例

Generating a stylized game prop image:

```
recommend
```
with the user's own words as
```
prompt
```
when the need is a capability;
```
search
```
with
```
target="models"
```
,
```
query="flux"
```
,
```
public=true
```
when you have a name.
```
search
```
ranks by keyword and its
```
filters
```
hold no capability key, so a capability-worded query can rank the wrong output type first. For the user's own trained models, omit
```
public
```
on
```
search
```
(
```
search
```
has no private flag); on
```
recommend
```
the flag is
```
include_private_models: true
```
. Re-discover ids each time: availability differs per team.
```
model_schema_get
```
on the pick: exact field names, types, required flags, defaults, and caps such as the prompt's
```
max_length
```
(an overrun is a 400, never a trim). File fields take asset ids even when named
```
...Url
```
, and
```
cost_impact: true
```
flags what moves the price.
If the schema carries
```
runs_as
```
(
```
"lora"
```
or
```
"composition"
```
), never send that model's own id to
```
model_run
```
. Its
```
run_with.required_arguments
```
holds the real call:
```
model_id
```
there is the base model, and its
```
parameters
```
(the
```
loras
```
or
```
modelId
```
wiring) merge into inputs from the same schema. Sending
```
required_arguments
```
alone discards your prompt.
Optional:
```
prompt_spark
```
rewrites a thin prompt into an on-model one; pass the discovered id (a LoRA's own, not its base) and the draft
```
prompt
```
. Skip deliberate prompts.
```
model_run
```
with
```
model_id
```
and schema-conformant
```
parameters
```
. If cost matters (the default assumption unless the user says otherwise), price first with
```
dry_run: true
```
, a top-level argument beside
```
model_id
```
: no job is created and the response's
```
creativeUnitsCost
```
is the exact payload's price; a
```
recommend
```
cost quote assumes defaults, and the schema's
```
cost_impact
```
fields move the real number. Then run: asset_ids come back, or a
```
job_id
```
for
```
jobs_wait
```
. The
```
status
```
beside it is
```
in_progress
```
when the server's wait budget ran out; with
```
wait=false
```
it is the backend's live word at creation (
```
queued
```
,
```
in-progress
```
,
```
warming-up
```
), a spelling that is not a different state.
```
jobs_wait
```
with
```
job_ids=[...]
```
(up to 32); each completed row carries
```
assetIds
```
and
```
cuCost
```
, so no
```
job_get
```
follow-up; on timeout re-call with the returned
```
pending_job_ids
```
as
```
job_ids
```
. Failed jobs are reimbursed, except xAI generations stopped by moderation.
```
asset_display
```
shows the asset inline; its
```
format
```
picks the rendering:
```
display
```
(the default) returns an inline image plus links and viewer data;
```
viewer
```
returns a lighter payload for a host that renders the interactive widget;
```
json
```
and
```
markdown
```
return metadata and links.
```
display
```
does not disable a host's widget. For PNG files, use
```
asset_download
```
with
```
format: "png"
```
, one call per asset.
```
asset_download
```
returns a file URL (save with
```
curl -L
```
, it may redirect).
```
format
```
is an image conversion (
```
png
```
,
```
webp
```
,
```
jpg
```
, and
```
gif
```
to keep an animated GIF animated: the
```
png
```
default flattens it to one frame) and nothing else; omit it for video, 3D, and audio. When
```
curl
```
reports
```
host_not_allowed
```
or
```
CONNECT tunnel failed, response 403
```
while MCP calls work, check the host's proxy or sandbox egress policy. A CDN 403 alone does not establish the cause; request a fresh download URL before diagnosing it: Sandbox network access names the setting that lifts it, an organization-level allowlist on some hosts that the user may not be able to change. Meanwhile hand over the
```
app_url
```
that
```
asset_display
```
returns, where the user downloads directly and, for a mesh, picks the 3D export format the app offers, none of which
```
asset_download
```
converts to. The signed URL also opens in a browser but expires, so it is a last resort, never the deliverable.

Local inputs go up with

upload_asset

: always

file_name

content_type

, and

kind

(

image

audio

video

3d

), plus exactly one of

file_size

data

, since the call fails without either. Prefer

file_size

, the file's exact byte count read from disk, and omit

data

: the reply carries presigned part URLs and

instructions

; PUT each part's raw bytes to its URL with no added headers (a checksum header makes the store answer 403), check every PUT returned 200, then

upload_asset_complete

with the

upload_id

. Inline base64

data

only under 100KB (that path returns the asset directly, with no complete step); a larger file is rejected naming the cap. Scope rides on both; they take no other fields: no parts list, no etags. The server decodes the file at completion, so

Upload upl_… failed: Corrupt JPEG data

premature end of data segment

bad Huffman code

libpng read error

means the uploaded image could not be decoded: check for a corrupt source, a truncated or re-encoded body, a missing part, or a mismatched

file_size

. Confirm the local file opens, its content type matches, and its byte count is correct, then start over with a fresh

upload_asset

and raw PUTs; never re-complete the same

upload_id

Unhandled image format

at upload lists what

kind: "image"

accepts: convert locally first. A host with no shell cannot PUT parts at all; the user uploads in the web app at app.scenario.com and the agent continues from the asset id.

Filing is part of delivering, not a tidy-up: run the catalog tools above with arguments under

parameters

(never

arguments

, which the executor drops silently, surfacing as a scope error that is not one).

collection_create

takes a name and the scope pair only;

asset_ids

sent there is ignored without an error, so adding is always a second call,

collection_add_assets

with

collection_id

and

asset_ids

, and re-adding a filed asset is a hard 400 naming the duplicate: drop it and continue. Confirm membership with

assets_get_bulk

and read each record's

collectionIds

;

search

filters={"collection_ids": [...]}

lags on a fresh write.

collection_add_assets

takes at most 49 ids per call (past it, 400

You can not add more than 49 assets at once

), so chunk a larger set.

asset_add_tags

is additive, one

asset_id

per call, so a set is one call per asset, and a tag the asset already carries returns 400

Duplicated tag

: read

tags

off

asset_get

first and send only the missing ones; skip the write when none are missing.

For reusable templates or reference content, follow the shared asset lifecycle: resolve existing assets, stage new versions, publish only through a supported operation, and verify public access before recording public IDs. Uploading and filing alone are not publication.

生成风格化游戏道具图像：

当需求是能力时，用用户自己的话作为
```
prompt
```
调用
```
recommend
```
；当你知道名称时，用
```
target="models"
```
、
```
query="flux"
```
、
```
public=true
```
调用
```
search
```
。
```
search
```
按关键字排序，且其
```
filters
```
没有能力键，因此用能力措辞的查询可能把错误的输出类型排在前面。对于用户自己训练的模型，在
```
search
```
上省略
```
public
```
（
```
search
```
没有 private 标志）；在
```
recommend
```
上该标志是
```
include_private_models: true
```
。每次重新发现 id：不同团队的可用性不同。
对选中的模型调用
```
model_schema_get
```
：确切的字段名、类型、必填标志、默认值和上限，例如提示词的
```
max_length
```
（超出会返回 400，绝不会自动截断）。文件字段即使命名为
```
...Url
```
也接受 asset id；
```
cost_impact: true
```
标记哪些字段会影响价格。
如果 schema 带有
```
runs_as
```
（
```
"lora"
```
或
```
"composition"
```
），绝不要将该模型自身的 id 传给
```
model_run
```
。它的
```
run_with.required_arguments
```
保存了真正的调用：其中的
```
model_id
```
是基础模型，其
```
parameters
```
（
```
loras
```
或
```
modelId
```
接线）会从同一 schema 合并到输入中。仅发送
```
required_arguments
```
会丢掉你的提示词。
可选：
```
prompt_spark
```
将单薄提示词改写成适合模型的版本；传入发现的 id（LoRA 自身的 id，而非其基础模型 id）和草稿
```
prompt
```
。刻意写好的提示词可跳过。
使用
```
model_id
```
和符合 schema 的
```
parameters
```
调用
```
model_run
```
。如果成本很重要（默认假设，除非用户另有说明），先用
```
dry_run: true
```
定价，它是
```
model_id
```
旁边的顶层参数：不会创建任务，响应的
```
creativeUnitsCost
```
就是该 payload 的确切价格；
```
recommend
```
的成本报价假设默认值，schema 的
```
cost_impact
```
字段会改变实际数字。然后运行：返回 asset_ids，或返回交给
```
jobs_wait
```
的
```
job_id
```
。旁边的
```
status
```
在服务器等待预算用尽时是
```
in_progress
```
；当
```
wait=false
```
时，它是后端创建时的实时状态（
```
queued
```
、
```
in-progress
```
、
```
warming-up
```
），这种拼写差异并不表示不同状态。
使用
```
job_ids=[...]
```
（最多 32 个）调用
```
jobs_wait
```
；每个完成行都带有
```
assetIds
```
和
```
cuCost
```
，因此不需要再调用
```
job_get
```
；超时后用返回的
```
pending_job_ids
```
作为
```
job_ids
```
重新调用。失败的任务会得到补偿，但被审核拦截的 xAI 生成除外。
```
asset_display
```
内联显示资产；其
```
format
```
决定渲染方式：
```
display
```
（默认）返回内联图像以及链接和查看器数据；
```
viewer
```
返回更轻量的 payload，供渲染交互式 widget 的主机使用；
```
json
```
和
```
markdown
```
返回元数据和链接。
```
display
```
不会禁用主机的 widget。对于 PNG 文件，使用
```
asset_download
```
并设置
```
format: "png"
```
，每个资产一次调用。
```
asset_download
```
返回文件 URL（使用
```
curl -L
```
保存，它可能会重定向）。
```
format
```
是图像转换（
```
png
```
、
```
webp
```
、
```
jpg
```
和
```
gif
```
——
```
gif
```
可保持动画 GIF 动起来：默认的
```
png
```
会将其压平为单帧），不支持其他类型；视频、3D 和音频请省略它。当 MCP 调用正常但
```
curl
```
报告
```
host_not_allowed
```
或
```
CONNECT tunnel failed, response 403
```
时，检查主机的代理或沙箱出口策略。单独的 CDN 403 不能确定原因；在诊断前先请求一个新的下载 URL：沙箱网络访问指出了解除该限制的设置——在某些主机上是组织级允许名单，用户可能无法更改。同时，把
```
asset_display
```
返回的
```
app_url
```
交给用户，让用户直接下载；对于网格（mesh），让用户选择应用提供的 3D 导出格式，这些格式
```
asset_download
```
都不会转换。签名 URL 也可以在浏览器中打开，但会过期，所以是最后手段，绝不是交付物。

本地输入通过

upload_asset

上传：始终提供

file_name

、

content_type

和

kind

（

image

、

audio

、

video

、

3d

），以及

file_size

或

data

中的恰好一个，因为缺少任何一个调用都会失败。优先使用

file_size

（从磁盘读取的文件确切字节数），并省略

data

：回复会携带预签名分片 URL 和

instructions

；将每个分片的原始字节 PUT 到其 URL，不要添加额外头部（校验和头部会导致存储返回 403），检查每个 PUT 都返回 200，然后调用

upload_asset_complete

并传入

upload_id

。内联 base64

data

仅限 100KB 以下（该路径直接返回资产，没有 complete 步骤）；更大的文件会被拒绝并说明上限。Scope 同时应用于这两个调用；它们不接受其他字段：没有分片列表，没有 etags。服务器在完成时解码文件，因此

Upload upl_… failed: Corrupt JPEG data

、

premature end of data segment

、

bad Huffman code

或

libpng read error

表示上传的图像无法解码：检查源文件是否损坏、正文是否被截断或重新编码、是否有缺失分片或

file_size

是否不匹配。确认本地文件可打开、内容类型匹配、字节数正确，然后重新发起一次全新的

upload_asset

和原始 PUT；绝不要重新 complete 同一个

upload_id

。上传时的

Unhandled image format

会列出

kind: "image"

接受的内容：先在本地转换。没有 shell 的主机根本无法 PUT 分片；用户可在 app.scenario.com 的 Web 应用中上传，agent 从 asset id 继续。

归档是交付的一部分，而不是事后整理：使用上面的目录工具，参数放在

parameters

下（绝不要放在

arguments

下，executor 会静默丢弃，表现为一个并非 scope 错误的 scope 错误）。

collection_create

只接受名称和 scope 对；发送到那里的

asset_ids

会被忽略且不报错，因此添加总是第二次调用：

collection_add_assets

，带上

collection_id

和

asset_ids

。重新添加已归档的资产会返回硬 400 并指出重复：放弃该资产并继续。用

assets_get_bulk

确认成员关系，并读取每条记录的

collectionIds

；

search

的

filters={"collection_ids": [...]}

在刚写入后会有延迟。

collection_add_assets

每次调用最多接受 49 个 id（超过会返回 400

You can not add more than 49 assets at once

），因此更大的集合要分块。

asset_add_tags

是追加式的，每次调用一个

asset_id

，因此一个集合需要每个资产一次调用；资产已携带的标签会返回 400

Duplicated tag

：先从

asset_get

读取

tags

，只发送缺失的标签；没有缺失就跳过写入。

对于可复用模板或参考内容，请遵循共享资产生命周期：先解析现有资产，暂存新版本，仅通过受支持的操作发布，并在记录公共 ID 前验证公共访问。仅上传和归档不算发布。

Errors and recovery

错误与恢复

Error	Recovery
`context_missing`	Nothing resolved: `teams_list` , then `projects_list`
`context_ambiguous`	Several fit: present the options; the user picks (non-interactive: task instructions name the pair, else stop and list)
403 Forbidden	Usually wrong scope, not missing: re-check the id pair
403 naming a plan	Surface the upgrade or switch models; retrying never clears it. `recommend` pre-flags these as `requires_plan_upgrade` (never run one) unless its response says plan gating is `_degraded` ; then this row is the backstop
429 with `details.actionName` = `parallel-custom-jobs`	Per-team generation concurrency ceiling: keep at most `actionLimit` jobs in flight, use `wait=false` for launches and `jobs_wait` to retire existing jobs before launching more. An immediate retry repeats the error
429 naming a quota, balance, or seat limit	Read the reason and `details` together, including `actionLimit` and `limitScope` when present. Generic plan-limit wording alone does not distinguish concurrency from consumption or feature access. A CU limit does not prove the balance is zero; the requested run may exceed what remains. Stop the affected batch, use `usage` for consumption, and report the stated remedy. A per-user cap goes to the team admin; a seat-cap error can also block uploads. Do not change billing or membership automatically
429 with an explicit retry delay	Respect the returned delay before retrying; this is not evidence that the user needs an upgrade
Other 429, including an unfamiliar `actionName`	Do not classify every other action as a count quota, or infer a training quota's behavior from its name. Report the error and run `diagnostics_run` in the same scope before choosing recovery
`jobs_wait` timeout ( `in_progress` )	Not an error: re-call with the returned `pending_job_ids` , never a second `model_run` or a cancel; it takes no timeout argument
Transport error on `model_run` (no HTTP status)	The request may still have landed: `jobs_list` before any re-run, or a lost response becomes a double charge; a `dry_run` call creates no job and always retries safely
400 `Cannot cancel this type of job`	A launched job is committed spend: `job_cancel` rejects most generation jobs, so plan batches with no abort path
400 `Invalid target format`	`format` converts images only: omit it for video, 3D, audio
`Either 'file_size' … or 'data' is required` on `upload_asset`	Read the byte count from disk and send it as `file_size` (omit `data` ); inline `data` is for files under 100KB only
`Upload upl_… failed: Corrupt JPEG data` (or `libpng read error` )	The uploaded image could not be decoded: check the source file, content type, byte count, and part transfers before a fresh upload; re-completing does not repair corrupt bytes
404 on `asset_get`	The id does not exist and no retry makes it appear: re-read `assetIds` off the `jobs_wait` or `job_get` row, since a guessed or mistyped id is the usual cause
400 `At least one of query, filter, image, or images must be provided`	`search` never lists bare: a "newest first" asset listing is `target="assets"` , `filter="createdAt EXISTS"` with `sort_by=["createdAt:desc"]`
`recommend` client-side timeout	It ranks on live data and commonly runs 30 seconds, sometimes over a minute: wait or re-call it; do not fall back to `search` for a capability

错误	恢复
`context_missing`	未解析任何内容： `teams_list` ，然后 `projects_list`
`context_ambiguous`	多个匹配：展示选项；由用户选择（非交互：任务指令指定这一对，否则停止并列出）
403 Forbidden	通常是 scope 错误而非缺失：重新检查 id 对
403 提及 plan	提示升级或切换模型；重试永远无法清除。 `recommend` 会预先将这些标记为 `requires_plan_upgrade` （绝不要自行升级），除非其响应说 plan 门控处于 `_degraded` ；此时这一行是兜底
429 且 `details.actionName` = `parallel-custom-jobs`	每个团队的生成并发上限：保持在飞任务数不超过 `actionLimit` ，启动时使用 `wait=false` ，并在启动更多任务前用 `jobs_wait` 结束已有任务。立即重试会重复该错误
429 提及配额、余额或席位限制	一起阅读 reason 和 `details` ，包括存在的 `actionLimit` 和 `limitScope` 。仅泛泛的 plan 限制措辞无法区分并发、消耗或功能访问。CU 限制并不证明余额为零；请求的运行可能超过剩余额度。停止受影响的批次，使用 `usage` 查看消耗，并报告所述补救措施。每用户上限需交给团队管理员；席位上限错误也可能阻止上传。不要自动更改计费或成员资格
429 且带有明确的重试延迟	重试前遵守返回的延迟；这不是用户需要升级的证据
其他 429，包括不熟悉的 `actionName`	不要将每个其他操作都归类为计数配额，也不要以名称推断训练配额的行为。报告错误，并在选择恢复方案前在同一 scope 内运行 `diagnostics_run`
`jobs_wait` 超时（ `in_progress` ）	不是错误：用返回的 `pending_job_ids` 重新调用，绝不要第二次 `model_run` 或取消；它不接受超时参数
`model_run` 上的传输错误（无 HTTP 状态）	请求可能已经到达：任何重跑前先 `jobs_list` ，否则丢失的响应会变成双重收费； `dry_run` 调用不会创建任务，始终可以安全重试
400 `Cannot cancel this type of job`	已启动的任务是承诺支出： `job_cancel` 会拒绝大多数生成任务，因此批次计划不应包含中止路径
400 `Invalid target format`	`format` 仅转换图像：视频、3D、音频请省略
`upload_asset` 报 `Either 'file_size' … or 'data' is required`	从磁盘读取字节数并作为 `file_size` 发送（省略 `data` ）；内联 `data` 仅适用于 100KB 以下文件
`Upload upl_… failed: Corrupt JPEG data` （或 `libpng read error` ）	上传的图像无法解码：在重新上传前检查源文件、内容类型、字节数和分片传输；重新 complete 无法修复损坏的字节
`asset_get` 返回 404	该 id 不存在，重试也不会使其出现：重新读取 `jobs_wait` 或 `job_get` 行上的 `assetIds` ，因为猜测或拼错的 id 是常见原因
400 `At least one of query, filter, image, or images must be provided`	`search` 从不做裸列表：“最新优先”的资产列表应使用 `target="assets"` 、 `filter="createdAt EXISTS"` 以及 `sort_by=["createdAt:desc"]`
`recommend` 客户端超时	它基于实时数据排序，通常需要 30 秒，有时超过一分钟：等待或重新调用；不要因为能力需求就回退到 `search`

Common mistakes

常见错误

A bare value where the schema says
```
array: true
```
: silently dropped, the run ignoring your reference or LoRA.
```
asset_get
```
on the output echoes what the run consumed (
```
metadata.referenceImages
```
,
```
parentId
```
), the cheapest proof it was not.
Taking
```
recommend
```
's
```
ranked[0]
```
blindly: read
```
next_step.type
```
first. On
```
ask_user
```
, present the options; the user's pick wins (non-interactive: task instructions, else
```
proceed
```
). On
```
proceed
```
, prefer
```
specialty.model_id
```
, else the first
```
ranked
```
entry its own text does not mark deprecated, reading
```
tradeoff
```
and
```
explanation
```
as well as
```
caveats
```
, since the flag lands in any of them: the ranking is by measured performance, not by lifecycle, so a deprecated member can top it.
Debugging blind: the
```
diagnose
```
MCP prompt (or
```
diagnostics_run
```
with the scope pair the failure happened under and any
```
mcpt_
```
ids seen as
```
observed_trace_ids
```
) returns trace ids;
```
usage
```
answers credit questions.
Guessing a file field's name: 400
```
Input image is required
```
(or
```
images
```
,
```
referenceImages
```
,
```
startImage
```
,
```
frontImage
```
,
```
video
```
,
```
model
```
, each a different model's name for the same idea) means the payload never carried the field the schema's
```
required
```
list names, so copy that name verbatim; a URL in a file field reads as missing too, since file fields take asset ids only.
Feeding an image field a video, audio, or 3D asset: 400
```
Unhandled image format
```
lists the image types it accepts.
```
asset_get
```
reports the asset's
```
mimeType
```
; pull a still with the clip's
```
firstFrame
```
when the model wants an image.
```
filters.kind
```
on
```
search
```
with
```
target="models"
```
: a 400
```
"kind" is not a filterable field
```
, since
```
kind
```
describes assets. Narrow models with
```
filters.type
```
(the architecture) or
```
tags
```
, or go through
```
recommend
```
for a capability.
Filtering
```
models_list
```
by
```
type
```
without
```
privacy: "public"
```
: a 400 says so. A private listing narrows by
```
status
```
or
```
modality
```
, or goes through
```
search
```
(private by default).

schema 声明
```
array: true
```
时传入了裸值：会被静默丢弃，运行会忽略你的参考图或 LoRA。对输出调用
```
asset_get
```
会回显运行实际消费的内容（
```
metadata.referenceImages
```
、
```
parentId
```
），这是证明未生效的最便宜方式。
盲目采用
```
recommend
```
的
```
ranked[0]
```
：先读
```
next_step.type
```
。若是
```
ask_user
```
，展示选项；以用户选择为准（非交互：按任务指令，否则
```
proceed
```
）。若是
```
proceed
```
，优先使用
```
specialty.model_id
```
，否则使用第一个
```
ranked
```
条目中其自身文本未标记为 deprecated 的项，并阅读
```
tradeoff
```
、
```
explanation
```
和
```
caveats
```
，因为该标志可能出现在其中任何一处：排序依据是实测性能而非生命周期，因此已弃用成员也可能排在最前。
盲目调试：
```
diagnose
```
MCP 提示（或使用失败发生时的 scope 对和任何观察到的
```
mcpt_
```
id 作为
```
observed_trace_ids
```
调用
```
diagnostics_run
```
）会返回 trace id；
```
usage
```
回答积分问题。
猜测文件字段名：400
```
Input image is required
```
（或
```
images
```
、
```
referenceImages
```
、
```
startImage
```
、
```
frontImage
```
、
```
video
```
、
```
model
```
——同一个概念在不同模型中名称不同）表示 payload 从未携带 schema 的
```
required
```
列表中指定的字段，因此要逐字复制该名称；文件字段中的 URL 也会被视为缺失，因为文件字段只接受 asset id。
给图像字段喂视频、音频或 3D 资产：400
```
Unhandled image format
```
会列出其接受的图像类型。
```
asset_get
```
报告资产的
```
mimeType
```
；当模型需要图像时，用剪辑的
```
firstFrame
```
提取静帧。
在
```
target="models"
```
的
```
search
```
上使用
```
filters.kind
```
：会返回 400
```
"kind" is not a filterable field
```
，因为
```
kind
```
描述资产。用
```
filters.type
```
（架构）或
```
tags
```
缩小模型范围，或通过
```
recommend
```
按能力查找。
在缺少
```
privacy: "public"
```
的情况下按
```
type
```
过滤
```
models_list
```
：会返回 400。私有列表按
```
status
```
或
```
modality
```
缩小范围，或通过
```
search
```
（默认私有）。