Metadata-Version: 2.4
Name: admatrix-client
Version: 0.5.0
Summary: Thin yc CLI for the existing ad-matrix generation API
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 亿创 Generation CLI

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

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

## 安装

从仓库安装：

```bash
pip install ./clients/python
```

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

```bash
pip install admatrix-client
```

安装后会提供 `yc` 命令。

## 配置环境

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

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

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

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

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

## 查看当前模型

```bash
yc models
```

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

## 上传本地参考图片

```bash
yc upload "./参考图.png"
```

支持 PNG、JPEG、WebP，单张最大 30 MiB、16 Mi 像素（例如 4096×4096）。CLI 读取指定文件，以
`multipart/form-data` 调用 `POST /api/matrix/aimake/v1/uploads/images`；
服务端校验完整图片并存到当前用户的上传目录，返回 `data.url`、`filename`、
`mime_type`、`size_bytes`、`width` 和 `height`。同一个 `YC_API_KEY` 即可使用。

脚本只需要 URL 时：

```bash
yc upload "./参考图.png" --url-only
```

将返回的 URL 填入模型 Schema 对应的图片字段，例如 Nano Banana 2.1 的
`input.ref_images`：

```bash
reference_url="$(yc upload "./参考图.png" --url-only)" &&
yc generate nano-banana-2-1 \
  --data "{\"input\":{\"prompt\":\"保留参考图中的主体，改成水彩风格\",\"ref_images\":[\"$reference_url\"]},\"request_num\":1}" \
  --wait
```

默认上传超时 120 秒，可用 `--timeout 300` 调整。上传失败时不输出成功 URL，
不会自动重发上传或提交生成。中文、空格及 `~` 路径均可使用；带空格的路径须加引号。

服务端每进程最多同时处理 2 个上传。按 API Key/JWT 所属用户统一限制：每 60 秒最多
10 次请求，同时最多 1 个上传；超过返回 HTTP 429 和 `Retry-After`，CLI 不自动重试。
每用户 CLI 图片存储最多 1 GiB、512 张；相同用户、相同文件内容会复用已有 URL，不重复占用配额。
配额根据 OBS 实际对象统计，服务重启不清零；达到容量或数量上限返回 HTTP 403。
限流或存储用量检查不可用时返回 HTTP 503，不继续上传。

图片 URL 长期保留，不自动过期。需要释放配额时，由管理员确认图片不再被引用后，清理
`<ObsUploadImage 中 %s 替换为 ai>/cli/<用户 ID>/` 下的对应 OBS 对象；下次上传会重新
统计实际用量。接口不会自动删除仍可能被模型引用的图片。部署时 OBS 凭据须具备此目录的
列举和写入权限；无需数据库迁移。

上传本身不创建生成任务、不扣积分，也不自动登记素材库或真人合规库。
后续模型调用仍按原规则计费，并校验该模型自己的参考图格式、大小、尺寸和数量限制。
需要登记真人合规素材时，先上传，再把 URL 交给 `yc compliance upload URL`。

此功能需要部署含上述上传接口的后端，并安装 `admatrix-client>=0.5.0`。

## 选择项目空间

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

```bash
yc project list
```

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

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

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

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

```bash
export YC_PROJECT_SPACE_ID="351622635392331776"
```

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

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

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

## 真人合规库

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

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

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

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

也可以单独查询：

```bash
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)` 已移除，改用：

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

## 提交并等待结果

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

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

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

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

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

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

## JSON 输入方式

内联 JSON：

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

从文件读取：

```bash
yc generate MODEL_ID --data @request.json
```

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

```bash
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 更容易发现并安全覆盖它。

## 查询已有任务

只查询一次：

```bash
yc status MODEL_ID GENERATION_ID
```

持续轮询最终结果：

```bash
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 转发到其他地址；请直接配置最终服务地址。

## 本期边界

仅 `yc upload` 会读取并上传明确指定的本地图片；`yc generate --data` 仍原样透传，
不会扫描或改写 JSON 中的本地路径。本包不提供结果自动下载、模型 Schema 校验、
API Key 创建或持久化。模型字段支持 base64 时，调用者可直接把
base64/data URL 写入 `--data`；CLI 仍原样透传，不做自动转换。
