亿创 Generation CLI

yc 是现有 ad-matrix generation API 的轻量命令行封装。它不保存模型列表， 也不理解任何模型的专属参数；模型 ID 和完整请求 JSON 会直接发送给服务端。

因此，只要新模型继续使用现有 generation API，CLI 就不需要更新或重新发布。

安装

从仓库安装：

pip install ./clients/python

发布到 Python 包仓库后可使用：

pip install admatrix-client

安装后会提供 yc 命令。

配置环境

CLI 不保存 API Key。调用前设置服务地址和个人 API Key：

export YC_BASE_URL="https://example.test"
export YC_API_KEY="your-api-key"

测试环境和正式环境使用同一个安装包，只需切换 YC_BASE_URL。也可以用一次性的 --base-url 覆盖环境变量：

yc --base-url "https://another.example" models

API Key 只能通过 YC_API_KEY 提供，不支持命令行参数，避免它进入命令历史和进程列表。

查看当前模型

yc models

模型来自服务端当前 registry，CLI 中没有模型 ID 白名单。

选择项目空间

查看当前 API Key 所属用户可以使用的项目空间：

yc project list

yc projects 是同一命令的快捷方式。

为单次生成指定项目空间：

yc generate gpt-image-2 \
  --project-space-id 351622635392331776 \
  --data '{"input":{"prompt":"一只在月球散步的猫"}}' \
  --wait

也可以设置默认项目空间：

export YC_PROJECT_SPACE_ID="351622635392331776"

选择顺序为 --project-space-id、--data 中已有的 project_space_id、 YC_PROJECT_SPACE_ID。都未提供时使用个人积分。设置了默认项目空间后，单次调用可用 --personal 强制改用个人积分：

yc generate gpt-image-2 \
  --personal \
  --data '{"input":{"prompt":"个人积分测试"}}'

CLI 最终发送的是 GenerateRequest 顶层的 project_space_id，不会把它放进模型 input。服务端会校验调用者的项目成员身份、项目状态和积分账户；校验失败时不会回退 扣个人积分。

真人合规库

通过公共可访问的图片 URL 登记到 Seedance 真人合规库：

yc compliance upload "https://cdn.example/person.png" --name "人物正面照"

接口会返回本地 id、审核状态和 asset_url。审核是异步的，可在登记时等待终态：

yc compliance upload "https://cdn.example/person.png" --wait

也可以单独查询：

yc compliance list --status Active
yc compliance get 123
yc compliance wait 123 --poll-interval 2 --wait-timeout 600

位置参数必须是绝对 HTTP(S) 图片 URL，图片格式、大小和访问权限由服务端校验。 CLI 使用同一个 YC_API_KEY，通过 POST /api/matrix/aimake/v1/ark-assets 发送 application/json，包含 name、asset_type: "Image" 和 source_url；它不会读取、 下载或上传图片内容，也不接受本地路径、file:// 或 base64/data URL。

--name 默认使用 URL 路径中的文件名去掉扩展名，忽略查询参数并解码文件名。 URL 没有文件名时必须显式提供 --name。带签名的 URL 会完整传给服务端；有效期应覆盖 素材处理所需时间，且必须允许服务端及素材审核服务读取。

返回的 asset://... 仅用于明确支持真人合规素材的模型字段；状态为 Active 后再提交生成。

从 0.3.x 迁移

0.4.0 起，yc compliance upload 的位置参数由本地文件路径改为图片 URL。 后端文件直传接口已经移除，请先准备公共可访问的图片 URL 再执行上述命令。 Python SDK 的 upload_compliance_image(path) 已移除，改用：

client.register_compliance_image("https://cdn.example/person.png", name="人物正面照")

提交并等待结果

--data 是现有 GenerateRequest 的完整 JSON：

yc generate seedance-2-0 \
  --data '{"input":{"prompt":"一只在月球散步的猫"},"request_num":1}' \
  --wait

CLI 只提交一次 generation 请求。拿到 gen_id 后，--wait 默认每 2 秒查询一次 status；任务进入 completed 后，输出包含 outputs、结果 URL 或失败原因的完整 JSON。

默认最长等待 1800 秒，可调整：

yc generate seedance-2-0 \
  --data @request.json \
  --wait \
  --poll-interval 3 \
  --wait-timeout 3600

轮询间隔和最长等待都必须是有限且大于 0 的秒数。 超时只会停止本地轮询，不会取消服务端任务。

JSON 输入方式

内联 JSON：

yc generate MODEL_ID --data '{"input":{"prompt":"hello"}}'

从文件读取：

yc generate MODEL_ID --data @request.json

从标准输入读取，适合 Codex 或脚本：

printf '%s' '{"input":{"prompt":"hello"}}' | yc generate MODEL_ID --data - --wait

CLI 会透传整个 JSON 对象，所以 provider_id、dry_run、ga_info、 callback_url 等现有通用字段不需要额外 CLI 参数。project_space_id 仍可直接写在 JSON 顶层；专用参数只是让人和 Agent 更容易发现并安全覆盖它。

查询已有任务

只查询一次：

yc status MODEL_ID GENERATION_ID

持续轮询最终结果：

yc wait MODEL_ID GENERATION_ID --poll-interval 2 --wait-timeout 1800

输出与退出状态

• 成功响应以 JSON 输出到 stdout，保持服务端的 code/detail/data 结构。
• 配置、输入、网络、API 或超时错误以 JSON 输出到 stderr。
• 成功退出码为 0，运行时/API 错误为 1，配置或输入错误为 2。
• 服务端即使返回 HTTP 200，只要业务 code 非 0，CLI 仍按失败处理。
• CLI 不跟随 HTTP 重定向，避免把 API Key 转发到其他地址；请直接配置最终服务地址。

本期边界

本包不自动上传或改写生成请求里的本地文件/URL，也不提供结果自动 下载、模型 Schema 校验、API Key 创建或持久化。模型字段支持 base64 时，调用者可直接把 base64/data URL 写入 --data；CLI 仍原样透传，不做自动转换。