scenario

场景

概述

Scenario 可通过 500 多种模型生成图像、视频、3D 内容和音频，还支持自定义训练。

设置

• 端点：https://mcp.scenario.com/mcp（Streamable HTTP）。优先使用 OAuth：不会在对话中传递凭据。
• 客户端配置、无头 API 密钥设置及各客户端重新进行身份验证的方法： references/setup.md。
• 切勿要求 Agent 收集、编码或回显机密。
• 之前已通过身份验证的连接现在失败：先重新进行身份验证，再排查问题。 diagnostics_run 会指出故障层（auth、tenant-scope、api-unreachable 或 healthy）。

两种工具类型：

• 直接工具：下方的循环，以及 asset_get、job_get、jobs_list 和 models_list。 ?toolsets=full 可显示所有工具。
• 目录工具：其余工具（集合、标记、分析、训练、成员、密钥）。
  • scenario_tools_search 仅接受 query（工具名称或关键词）和 limit；返回架构和通道。
  • scenario_tool_execute_read / write / delete 使用 {name, parameters} 运行工具。
  • 所有输入都放在 parameters 中，包括作用域 ID 和 dry_run。几乎所有目录工具都声明了作用域 ID；plan_generation 只接受 description。
  • 直接工具在顶层接受作用域，而 model_run 的 dry_run 也在顶层传入。
  • 执行器会静默丢弃放错位置的键：arguments 会导致虚假的作用域错误，而顶层的 dry_run 会直接运行任务并产生费用。
  • 通道由结果自身的 permission 决定，而非由动词决定：asset_download 和 asset_analyze 属于写入类。

先确定作用域

• 先确定作用域，然后在每次调用时传入 team_id 和 project_id。
• teams_list 会返回团队及其项目。projects_list 需要 team_id，因此不能先调用它。
• 与用户确认这组 ID：猜错会将内容写入他人的项目。无人值守时，从任务中获取这组 ID；如果任务未指定，则停止并列出可选项。
• 服务器仅会在候选项唯一时为只读工具填入作用域。否则调用会失败，并指出缺少哪一项。
• 新增第二个团队或项目后，遗漏作用域通常会导致调用失败。

快速参考

步骤	工具	说明
确定范围	teams_list，然后 projects_list	每个会话执行一次；每次调用都传入这些 ID
查找模型	search 或 recommend	免费；按能力查找用 recommend，按名称查找用 search
获取架构	model_schema_get	始终在 model_run 之前调用；检查 runs_as 和 caps
生成	model_run	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 提示词
已保存的偏好	memory_recall	仅限 OAuth；在项目中生成前调用，切换后再次调用

• 多步骤请求（“带配音的产品视频”“从概念到 3D”）：使用目录中的 plan_generation（读取通道）。在 description 中用普通语言描述，按顺序列出步骤，每个步骤注明一个工具 和可选的模型提示。该工具不会执行任何操作。单一步骤请求使用 recommend。
• 明确表达的偏好（“始终使用 9:16”）：使用目录中的 memory_set（删除通道），scope 为 project_user_memory（跨项目使用 user_memory）。该操作会替换整个层：先调用 memory_get 并合并。

示例

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

1. 发现模型：
   • 使用用户自己的措辞，通过 recommend 的 prompt 查询所需能力。
   • 对于已知名称，使用 search，并设置 target="models"、query="<model name>"、public=true。它按关键词排序，且其 filters 不包含能力键，因此使用能力描述的查询可能会把错误的输出类型排在最前面。
   • 用户自己训练的模型：在 search 中省略 public（它没有私有标志）；在 recommend 中传入 include_private_models: true。
   • 每次都重新发现 ID：不同团队的可用模型各不相同。
2. 对选定模型调用 model_schema_get：获取准确的字段名称、类型、必填标志、默认值和上限。
   • 超过上限（例如提示词的 max_length）会返回 400 错误，不会截断内容。
   • 文件字段接受资源 ID，即使字段名是 ...Url 也一样。
   • cost_impact: true 标记会影响价格的字段。
3. 如果架构中包含 runs_as（"lora" 或 "composition"），绝不能将该模型的 ID 传给 model_run。其 run_with.required_arguments 中包含实际调用参数：其中的 model_id 是基础模型，而其中的 parameters（loras 或 modelId 接线参数）会与同一架构中的输入合并。单独使用 required_arguments 会丢弃你的提示词。
4. 可选：prompt_spark 可将简短的提示词改写为适用于模型的提示词。传入已发现的 ID（LoRA 自身的 ID，而非其基础模型的 ID）和草稿 prompt。有意写好的提示词则跳过此步骤。
5. 使用符合架构的 model_id 和 parameters 调用 model_run。
   • 除非用户表示不在意成本，否则先用 dry_run: true 估价，并将其放在顶层，与 model_id 并列。此操作不会创建任务；creativeUnitsCost 是这份确切载荷的价格。
   • recommend 的报价假设使用默认值；cost_impact 字段会影响实际价格。
   • 运行：内联资源（status: success）无需等待；否则将 job_id 传给 jobs_wait。
   • 未完成状态：等待超时后为 in_progress；使用 wait=false 时则为 queued、in-progress 或 warming-up。这些状态都需要调用 jobs_wait。
6. 使用 job_ids=[...] 调用 jobs_wait（最多 32 个）。
   • 每条已完成的记录都包含 assetIds 和 cuCost：无需再调用 job_get。
   • 超时后（in_progress），使用 pending_job_ids 作为 job_ids 再次调用；切勿重新运行或取消任务。此操作没有超时参数。
   • 失败的任务会退款，但因审核而停止的 xAI 生成除外。
7. asset_display 会以内联方式显示资源。其 format 决定渲染方式：
   • display（默认）：显示内联图像、链接和查看器数据；不会禁用宿主的微件。
   • viewer：为渲染交互式微件的宿主提供更轻量的载荷。
   • json、markdown：提供元数据和链接。
8. asset_download 每次为一个资源返回文件 URL；使用 curl -L 保存（URL 可能会重定向）。
   • format 可转换图像（png、webp、jpg；gif 会保留动画，而默认的 png 会将其展平为单帧）和网格（glb、fbx、obj）。下载视频和音频时应省略此参数，否则会因 Invalid target format 返回 400 错误。
   • 如果 MCP 调用正常，但 curl 因 host_not_allowed 或 CONNECT tunnel failed, response 403 失败，说明问题可能出在宿主的出站网络策略上。仅 CDN 返回 403 并不能说明这一点：请先获取新的 URL。
   • 沙盒网络访问介绍了相关设置。在某些宿主上，这是一份组织级允许列表，用户可能无权修改。
   • 与此同时，提供 asset_display 的 app_url。用户可在那里下载；对于网格，还可以选择 asset_download 不提供的导出格式。
   • 签名 URL 会过期：这是最后的备用方案，绝不能作为交付成果。

本地输入通过 upload_asset 上传：

• 始终提供 file_name、content_type 和 kind（image、audio、video、3d），并且在 file_size 和 data 中二选一。两者都没有时会失败，并提示 Either 'file_size' … or 'data' is required。
• 优先使用 file_size，填写从磁盘读取的准确字节数，并省略 data。回复会提供预签名分段 URL 和 instructions。
• 将每个分段的原始字节 PUT 到对应 URL，不要添加任何请求头：校验和请求头会导致存储端返回 403。检查每次 PUT 均返回 200，然后使用 upload_id 调用 upload_asset_complete。
• 仅在没有 shell 可用于 PUT 分段时，才使用小于 100KB 的内联 base64 data。此方式会直接返回资源，无需完成步骤；更大的文件会被拒绝，并提示大小上限。
• 两个调用都只接受 scope，不接受其他内容：没有分段列表，也没有 etag。
• 内联 data 会在 upload_asset 内解码：如果此处出现解码错误（libpng read error、Corrupt JPEG data、unable to read pixels），说明 base64 字符串损坏，而非文件损坏。
  • Agent 需要逐个重新输入 data 中的字符；一个 57K 字符的字符串就曾因此损坏。
  • 重新发送只会重复报错。如果有 shell，请改用 file_size 路径，即使用户要求内联方式也是如此，并说明原因。
• 使用 file_size 路径时，服务端会在完成时解码：如果出现 Upload upl_… failed:，并伴有 Corrupt JPEG data、premature end of data segment、bad Huffman code 或 libpng read error，则表示解码失败。
  • 检查源文件是否损坏、请求体是否被截断或重新编码、是否缺少分段，或 file_size 是否错误。
  • 确认本地文件能够以声明的内容类型打开，然后使用新的 upload_asset 重新开始，并 PUT 原始分段。切勿对同一个 upload_id 再次执行完成操作。
• 手机拍摄的 HEIC 照片应原样上传（content_type: "image/heic"）：不要转换。Unhandled image format 会列出 kind: "image" 支持的格式；其他类型应在本地转换。
• 没有 shell 的主机无法 PUT 分段。用户会在 app.scenario.com 上传，Agent 随后通过资源 ID 继续操作。

归档是交付流程的一部分，不是收尾工作：

• collection_create 只接受名称和 scope 对。发送到其中的 asset_ids 会被静默忽略，因此添加资源始终需要单独调用 collection_add_assets，并提供 collection_id 和 asset_ids。
• 它接受任意数量的 ID，按 49 个一批处理，并跳过重复项。结果会分别列出 already_present_asset_ids 和 added_asset_ids。
• 失败后可以安全地重新发送整个列表：错误计数的是新增项；重试会添加剩余项。
• 请以该回复为准进行确认：刚写入的数据不会立即反映在 search filters={"collection_ids": [...]} 中。
• asset_add_tags 采用追加方式，每次接受一个 asset_id。如果资源已有某个标签，会返回 400 Duplicated tag：先通过 assets_get_bulk 读取 tags，然后只发送缺少的标签。

可复用模板和参考内容遵循 共享资源生命周期：解析现有资源，暂存新版本，仅通过受支持的操作发布，并在记录公开 ID 之前验证公开访问权限。仅上传和归档并不代表已发布。

错误与恢复

• context_missing：未解析到任何内容。必要时调用 teams_list、projects_list。
• context_ambiguous：有多个匹配项。列出选项，让用户选择（无人值守时：任务会指定这对内容，否则停止并列出选项）。
• 403 Forbidden：通常是范围错误，而非内容缺失；重新检查 ID 对。私有素材输入只能从其所属项目读取：
  • 询问素材属于哪个项目（无人值守时：任务会指定，否则停止）；
  • 使用该项目作为 project_id，并提供 asset_id 和 target_project_id，调用目录中的 asset_copy（写入通道）；
  • 使用返回的 ID。asset_copy 只能在同一团队的项目之间复制。
• 403 指明套餐：提示升级或切换模型；重试无法解决问题。recommend 会将这些情况预先标记为 requires_plan_upgrade（绝不运行），除非其响应指出套餐限制检查处于 _degraded 状态；此时本条规则作为兜底。
• 429，且 details.actionName = parallel-custom-jobs：团队级生成并发上限。最多同时运行 actionLimit 个作业：使用 wait=false 启动作业，并在启动更多作业前通过 jobs_wait 完成作业。立即重试会再次报错。
• 429 custom-generation，或指明配额、余额或席位上限：
  • actionLimit 是该时段的 CU 配额（Free：每天 50），actionValue 是已消耗的数量。定价高于剩余额度的运行会被拒绝，因此 actionValue 较低意味着此负载成本过高，而不是额度已耗尽。
  • 停止批次，对负载运行 dry_run，提供更便宜的成员选项或减少输出数量，或者说明重置时间或升级方案（无人值守时：说明情况并停止）。
  • usage 使用相同的 project_id（或 scope: "team"）。
  • 用户级上限需联系团队管理员；席位上限错误也可能阻止上传。切勿自行更改账单或成员资格。
• 429 Too Many Requests. Please, wait N seconds（remainingSeconds）：Relax 模式：套餐的 CU 已用完，因此每个作业都需要等待。
  • 等待时间随负载成本而变化：高强度等级、长视频等高成本作业可能仍处于锁定状态，而较便宜的作业可以运行。在 remainingSeconds 内切勿重新提交相同负载。
  • 任何团队成员的作业都会重置团队的等待时间；团队持续生成时，等待时间会延长，因此批次会变慢。被拒绝的尝试不收费。
  • 根据此次拒绝判断是否处于 Relax 模式：usage 报告的是已消耗量，而非剩余 CU。如果没有任何工具说明如何检查等待时间，请说明无法确定。
  • 停止批次。提供 CU 充值（可立即结束 Relax 模式）或升级方案；否则提供更便宜的负载（先运行 dry_run）、减少输出数量，或建议稍后运行（无人值守时：说明情况并停止，绝不重新启动）。
  • 规则和套餐上限： Relax 模式。
• 其他 429，包括不熟悉的 actionName：切勿根据名称推断其行为。说明情况，并在选择恢复方式前于相同范围内运行 diagnostics_run。
• model_run 发生传输错误（无 HTTP 状态码）：请求可能仍已提交。任何重跑前先运行 jobs_list，否则丢失的响应会导致重复扣费。dry_run 不会创建作业，始终可以安全重试。
• 400 Cannot cancel this type of job：已启动的作业会产生确定的费用。job_cancel 会拒绝大多数生成作业，因此规划批次时不要指望能够中止。
• 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 查询能力。

常见错误

• 使用占位符 ID（asset_placeholder）为后续步骤定价：文件 ID 会在定价前解析，因此 dry_run 会返回 404，且不给出报价。先通过 recommend 获取报价，等实际资产存在后再运行 dry_run。
• 在架构要求 array: true 时传入单个值：该值会被静默丢弃，因此运行时会忽略你的参考图或 LoRA。对输出调用 asset_get 会回显运行实际使用的内容（metadata.referenceImages、parentId），这是成本最低的验证方式。
• 不加判断地采用 recommend 的 ranked[0]。先查看 next_step.type：
  • no_match：停止生成，即使有部分匹配的选项也一样。说明 unmet_requirements 和 suggested_action；绝不要悄悄放宽要求。架构检查或成功的 dry run 都不能推翻 no_match。
  • ask_user：展示选项；以用户的选择为准（无人值守时：使用任务指定的选项，否则使用 proceed）。
  • proceed：优先选择 specialty.model_id，否则选择第一条未在其 caveats、tradeoff 或 explanation 中标记为已弃用的 ranked 条目。排名衡量的是性能，而非生命周期状态。
• 盲目调试：diagnose MCP 提示词会返回跟踪 ID，diagnostics_run 也会；调用时需提供失败调用的作用域对，并将任何已发现的 mcpt_ ID 作为 observed_trace_ids 传入。
• 猜测文件字段的名称：出现 400 Input image is required（或 referenceImages、startImage、frontImage、video；每个模型都有各自的字段名），意味着载荷缺少架构要求的 required 字段。照原样复制字段名。在该字段中传入 URL 会被视为缺失：文件字段只接受资产 ID。
• 向图像字段传入视频、音频或 3D 资产：400 Unhandled image format 会列出接受的类型。asset_get 会报告资产的 mimeType；如果模型需要图像，可使用片段的 firstFrame 提取静帧。
• 在 search 中使用 target="models" 时设置 filters.kind：会返回 400 "kind" is not a filterable field，因为 kind 描述的是资产。通过 filters.type（架构类型）或 tags 缩小模型范围，或用 recommend 推荐符合能力要求的模型。
• 未设置 privacy: "public" 就按 type 筛选 models_list：会收到 400 错误。私有列表可按 status 或 modality 缩小范围，或使用 search（默认搜索私有内容）。