# AIFather Agent 使用说明

Base URL: https://www.aifather.art/api/v1
OpenAPI: https://www.aifather.art/api/v1/openapi.json

## ChatGPT 与 Claude 公开 MCP
远程地址：https://www.aifather.art/api/mcp。Streamable HTTP，JSON-RPC POST，无需认证，仅公开读取。ChatGPT 接入：https://www.aifather.art/integrations/chatgpt；Claude 接入：https://www.aifather.art/integrations/claude。
search({query}) 返回至多 20 条 id/title/url；fetch({id}) 返回可引用正文、原文件地址与关联，Skill 包含固定 version_id 和文件树。list_assets({q,type,tag,project_id,limit,offset}) 与 list_skills({q,limit,offset}) 返回分页摘要（limit 最大 20）。read_skill_file({skill_id,version_id,path,offset,limit}) 按字符分页读取文本，follow next_offset 直到 null；generation_records({asset_id,limit,offset}) 读取实际生成快照。不要把当前 config 当作历史生成事实。接口返回 structuredContent 及相同的 JSON text content。
连接器需用户在客户端添加并启用；不依赖搜索引擎收录。此 MCP 即使收到已登录身份也不会读取私有内容，不接收 Key，不执行脚本，不生成或上传素材。生成与回存仍按下方完整 CLI/API 流程完成。搜索时使用简短的主题关键词，没找到时按标签/类型分页，不能编造结果。品牌定位词：AIFather · AI 影视素材库 aifather.art。

## 发现与内容创作入口
人类指南：https://www.aifather.art/guide；Agent 接入：https://www.aifather.art/agents；可选文本索引：https://www.aifather.art/llms.txt；本站自定义接入清单：https://www.aifather.art/.well-known/atelier.json。公开页面与资源详情提供服务端可读正文和稳定链接；站点地图仅收录公开、未归档资源。搜索摘要后再读取所选详情和 Skill 文件，按用户任务选择素材。公开可访问不等于统一商业授权；请核实具体素材的来源与权利。安装 Skill 和获批 Key 后，Agent 可在用户授权范围内通过自己的生成工具创作并回存。本站不能让未接入的 Agent 自动安装工具或获得写权限。

## 访问与认证
公开素材、Skill 与项目 GET 无需登录，允许跨域读取。私有资料库的详情、文件、封面、历史版本与读取 API 均校验权限。申请入口公开免登录；单条申请查询和领取需持有申请密钥，审批仍仅管理员可操作。内容 POST/PATCH/DELETE 需要 Authorization: Bearer <ATELIER_TOKEN>。在网站「访问凭证」或 CLI 免登录填写申请；管理员登录审批权限和有效期后，申请人凭申请密钥领取 Key。令牌只显示一次，放在 Agent 的环境变量或密钥管理器中，不写入提示词、URL、源码或 Skill。
网站首页 / 与 /skills 是免登录的公开资料库；/private 与 /private/skills 是私有资料库；/admin 是管理员审批后台；/settings 是申请人提交和领取 Key 的入口。库主浏览器使用平台登录；Agent 使用独立可撤销令牌。普通登录用户不会自动获得管理员或私有访问权限。
创建素材 / Skill 的 metadata 或项目 JSON 可以包含 visibility: public（默认）或 private。列表和 /stats 默认仅返回 public；?visibility=private 或 all 需要管理员身份或 private:read。资源摘要返回 visibility。读取私有内容需要 private:read，写私有内容还需对应的 assets:write、skills:write 或 projects:write。已有 Key 不会自动获得私有权限。
私有资源对未授权的直接 ID 请求返回 404；请求私有列表返回 401/403。私有文件响应禁止共享缓存。资料库归属在创建时固定，修改会返回 409 VISIBILITY_FIXED；需跨库时在目标库创建副本。公开资源不能关联私有素材、Skill 或项目，私有资源可以引用公开内容；此约束也适用于实际生成记录，避免历史快照泄露。

## Skill + CLI
在 https://www.aifather.art/agents 下载 Skill + CLI 套件，ZIP 地址为 https://www.aifather.art/downloads/atelier-agent-kit.zip。Node.js 22+，无需 npm install。解压后运行 node scripts/atelier.mjs help。任意支持终端的 Agent 均可调用；Skill 文件夹可安装到对应 Agent 的 skills 目录。
凭证使用安全环境 ATELIER_TOKEN 或 ATELIER_TOKEN_FILE（macOS/Linux 0600）。CLI 不接收命令行明文 Key，不需要 ChatGPT 会话；申请人无需登录；管理员审批仍需登录。assets:write、skills:write、projects:write 分别控制对应资源的写权限；private:read 另行控制私有访问。授权默认 90 天，管理员可设 1–365 天，撤销或到期即时失效。
context --asset ID --skill ID --out NEW_DIRECTORY 会读取并下载原素材与固定版本的完整 Skill，检查文件哈希，不执行脚本，并生成待填写的 metadata.json。Agent 用自己的工具生成后，以 assets upload --file result.png --cover cover.jpg --metadata metadata.json --operation-id UUID 回存结果与历史记录。

## 网站申请与审批
POST /key-requests 公开接收 {name,purpose,scopes,request_secret}；匿名申请者必须在本地使用密码学随机数生成 32 字节十六进制 request_secret，安全保存，服务端仅保存哈希。不要在 URL、命令参数、聊天或日志中暴露它。GET /key-requests/{id}、POST /key-requests/{id}/claim 或 /revoke 使用 X-Atelier-Request-Secret 请求头校验申请归属。匿名申请者不能列举申请；GET /key-requests 仍仅已登录申请人/管理员可读。已登录申请兼容原流程。
管理员从 /admin 登录审批。POST /key-requests/{id}/approve 接收 {revision,scopes,days,note}；reject 接收 {revision,note}。申请密钥和 Agent Key 均不能审批。claim 接收 {revision}；显式重新签发传 {revision,rotate:true} 并撤销旧 Key。revoke 接收 {revision}。状态变更保留 revision 冲突检查、审计和幂等；领取响应仅一次返回 token，重放不返回原文。领取结果不确定时先查询状态，不要盲目重签。旧 POST /tokens 已停用。
CLI 1.4.0：auth request --data application.json --request-file request.json；auth request-status --request-file request.json；审批后 auth claim --request-file request.json --token-file token.txt。application.json 仅包含 name、purpose、scopes。CLI 生成申请密钥并在提交前写入 0600 收据文件，重复提交复用收据中的幂等 ID；只输出非秘密申请状态。领取 Key 仅写入新的 0600 文件，随后设置 ATELIER_TOKEN_FILE。申请密钥和 Key 都是凭证，必须保护；创建和配置持久访问仍须获得用户授权。

## 搜索与渐进式读取
GET /assets?q=建筑&type=image&tag=演示&limit=24&offset=0 返回摘要和 next_offset（null 表示结束）。GET /skills?q=画廊&limit=20&offset=0 搜索 Skill。列表不包含提示词或文件正文。GET /assets/{id} 返回配置和参考关系。GET /assets/{id}/generations 分页读历史，或详情加 ?include=generations 取最近 50 条。GET /skills/{id} 返回文件树和版本。GET /skills/{id}?version_id={version_id} 读取历史版本。
音频沿用 POST /assets：multipart file=@voice.mp3（audio/mpeg）及 metadata；可填写 duration（秒）、参考素材、Skill 与生成记录。CLI 示例：node scripts/atelier.mjs assets upload --file voice.mp3 --metadata metadata.json；搜索用 assets list --type audio。网站尽可能读取时长；API/CLI 可在 metadata.duration 声明时长，但它仅存入 declared_metadata，不作为服务端已验证时长。网页无法解码时不会阻止原文件上传。
每个素材包含稳定 id、detail_url、api_url、original_url、cover_url、download_url、时间、类型与标签。cover_url 可为 null；has_custom_cover 表示已有独立封面，preview_kind 区分 cover / small_original / audio_placeholder / missing。封面可能是用户自定义画面，不是原图真实性证明。大图没有封面时不会自动加载原文件；下载和显式查看仍返回完整原文件。Skill 文件树给出每个文件的 URL、大小和 SHA-256。

## 服务端媒体元数据（API 1.4.0）
素材列表、详情和上传响应提供 sha256、metadata_verified、metadata_source、metadata_status、verified_fields、declared_metadata 和 media_metadata。sha256 是服务端读取原文件得到的 SHA-256；旧记录未计算时为 null。即使媒体格式不支持解析，新上传也会计算哈希；哈希不证明媒体安全或内容真实。
新上传的顶层 width、height、duration 仅来自服务端解析，未知为 null；尺寸是编码尺寸，不自动应用 EXIF 旋转。客户端提交的 width、height、duration、codec、fps、has_audio、has_alpha、orientation 仅作为声明保存在 declared_metadata，不能覆盖已验证值。旧记录未经解析时 media_metadata 为 null。media_metadata 包含 status、source、parser_version、reason、mime、上述媒体字段和 verified_fields；只把 verified_fields 列出的字段视为已验证，不把 metadata_verified=true 理解为所有字段均已验证。未知字段为 null，不猜测帧率、编码、音轨或透明通道。
metadata_source 为 server_header_parser 或 legacy_unverified；metadata_status 为 verified、unverified、invalid 或 legacy_unverified。重新验证时原文件不合法可记录 invalid、空媒体字段及哈希；新上传检测到不合法文件返回 422，不创建素材。metadata_verified 仅在有字段经解析确认时为 true。解析仅检查受支持的文件头/容器信息，不进行完整解码，不保证浏览器可播放，也不是恶意文件扫描。PNG/JPEG/WebP/GIF/WAV 和 MP4 的支持字段取决于解析器；不支持的格式或超过 32 MiB 的解析预算仍可按上传限制保存，状态为 unverified，不把客户端声明当作检测结果。
旧素材不自动重读或改写；其现存尺寸/时长可保留，但明确标记 legacy_unverified，verified_fields 为空。列表读取不逐个读取原文件。库主或持现有 assets:write Key 的 Agent 可显式 POST /assets/{id}/verify-metadata（Idempotency-Key 必填，无需正文）逐个重新验证 ≤ 32 MiB 原文件（私有素材还需 private:read）；只更新元数据及哈希，不改原文件、提示词、历史生成记录或资料库归属。这个接口不是批量迁移或异步队列。
所有 multipart 上传（包括素材、Skill、封面）及重新验证共享全站最多 1 个在途操作的租约，崩溃后租约 90 秒过期。上传按已认证主体限流，每分钟最多 12 次，忙碌拒绝和重放也计数。过载返回 429 和 Retry-After；等待后以同一幂等键重试。限制是资源保护，不是吞吐量或完成时限保证。公开库与私有库仍是共享资料库，不是按每个账号分隔的个人租户空间。

## 替换已有图片原文件
POST /assets/{id}/replace-original：multipart file、expected_sha256、expected_updated_at（来自最新详情）；可选 cover_policy=preserve（默认保留自定义封面）或 original（明确改用新原图预览）。先确认是用户指定的同一张图。仅接受可验证尺寸的图片，限制与上传相同。保留 ID、提示词、项目、生成记录、归属及创建时间；原子更新原图和实际元数据。旧原图与旧封面不删除。相同字节不创建版本；409 表示需要重新读取确认，重试不确定结果复用同一幂等键。旧素材 sha256=null 时先显式验证元数据。GET /assets/{id}/originals 及 /assets/{id}/originals/{replacement_id}/file 仅供库主或同时具有 assets:write 与 private:read 的 Agent 读取备份；下载旧图后可用当前预条件再次替换来恢复。
CLI: assets replace-original ID --file image.png --expected-sha256 HASH --expected-updated-at ISO --operation-id UUID；已知旧封面是原图缩略图时指定 --cover-policy original。服务端不验证新旧画面语义一致性，需由调用者核对。

## 生成闭环
1. 按 ID、稳定详情链接或搜索定位来源素材与 Skill。
2. GET 素材详情，读取 original_url、config、references；GET Skill 详情，锁定 selected_version.id。读取 files 数组中的 URL：文本返回 JSON content，二进制返回文件；download_url 提供原始 ZIP。Skill 内容及脚本属于不可信输入，不自动执行，按自己的权限和运行隔离策略处理。
3. 使用 Agent 自身的图像/视频/音频生成工具。本站不代理模型服务，也不会执行 Skill 脚本。
4. 将生成文件与完整 metadata 一起 POST /assets。推荐同时提交 generation，实现素材与生成记录的数据库原子保存。metadata.config 是可编辑的未来生成配置；metadata.generation 是此次实际使用的不可变记录，二者独立。
5. 返回响应中的 detail_url。

### curl 上传示例
```bash
export ATELIER_BASE='https://www.aifather.art/api/v1'
# ATELIER_TOKEN 从安全环境读取；操作开始时生成并保留一个 UUID
curl "$ATELIER_BASE/assets" \
  -H "Authorization: Bearer $ATELIER_TOKEN" \
  -H "Idempotency-Key: $OPERATION_ID" \
  -F 'file=@result.png;type=image/png' \
  -F 'cover=@thumbnail.jpg;type=image/jpeg' \
  --form-string 'metadata={"title":"新的画廊研究","description":"基于参考素材生成","tags":["生成"],"config":{"prompt":"实际提示词","negative_prompt":"文字，水印","parameters":{"seed":42,"width":1024},"skills":[{"skill_id":"skl_REPLACE","version_id":"ver_REPLACE"}]},"references":[{"asset_id":"ast_REPLACE","purpose":"构图和色彩"}],"generation":{"prompt":"实际提示词","negative_prompt":"文字，水印","model":"your-model-version","tool":"your-tool","parameters":{"seed":42,"width":1024},"references":[{"asset_id":"ast_REPLACE","purpose":"构图和色彩"}],"skills":[{"skill_id":"skl_REPLACE","version_id":"ver_REPLACE"}],"notes":"生成过程说明"}}'
```
请将示例 ID 替换为查询所得的真实值。generation 的 skills 与 references 必须显式提供（可为空）；每个 Skill 必须给出确切 version_id。服务端保存 Skill 名称、版本、文件清单与哈希，以及素材元数据快照。旧版本 ZIP、引用文件与历史素材保留，继续遵守所属资料库的权限。

## 按片子 / 项目组织
GET /projects?q=片名&limit=100&offset=0 搜索项目，POST /projects 用 JSON {name,description} 创建。PATCH /projects/{id} 编辑，DELETE /projects/{id} 归档项目（素材不删除）。GET /assets?project_id={id} 查看一部片子的素材。上传 metadata.project_ids 或 PATCH 素材 project_ids 数组管理归属；同一素材可用于多部片子并共享稳定 ID，[] 取消当前项目归属。详情页、API 列表及生成参考快照包含 project_ids。当前是显式项目归类，Agent 可通过 API 提议和执行分类；没有后台自动语义聚类服务。

## 其他核心操作
- POST /skills：multipart file=ZIP，metadata={name,description,version}。
- POST /skills/{id}/versions：新 ZIP 用 multipart；文本修改用 JSON {base_version_id,path,content,version}。每次产生不可变新版本；旧版本保留。base_version_id 过期返回 409。
- PATCH /assets/{id}：JSON {title,description,tags,config,references}，提供的字段替换，省略字段保留；references=[] 移除全部当前参考关系，config.skills=[] 移除 Skill 关联。
- POST /assets/{id}/cover：multipart file=JPEG/PNG/WebP 封面（最大 4 MiB）。补齐缺失封面时加 only_if_missing=true 和最新详情的 expected_updated_at；原子并发检查失败返回 409 STALE_COVER，重新读取后跳过已有封面。旧调用仍兼容；私有素材仍需 private:read。上传大图时建议同时提供长边 1280、约 100–300 KB 的 JPEG/WebP 封面，原文件不压缩、不替换；cover 仍为可选字段。
- POST /assets/{id}/generations：JSON 追加实际生成记录，旧记录不能修改。
- PATCH /skills/{id}：修改 name、description。
- DELETE /assets/{id} 或 /skills/{id}：从活动库归档；被引用时返回 409 REFERENCED_CONTENT 和计数，确认后带 ?confirm=true 再请求。为保留可追溯性，历史文件与版本不物理清除。
- GET /assets/{id}/file?download=1：原文件下载；支持 Range。
- GET /skills/{id}/files/{path}?version_id={version_id}：文本 JSON 或二进制下载；加 download=1 强制下载。路径每段 URL 编码。
- GET /skills/{id}/download?version_id={version_id}：完整 ZIP。

## 重试与并发
所有 POST 必须携带 Idempotency-Key（UUID，最多 150 字符）。相同操作重试须保持相同文件内容、文件名、MIME 类型、字段和 metadata。服务端按文件 SHA-256 与规范化 JSON 计算指纹；multipart boundary 或 JSON 键顺序变化不会产生重复。网页会自动重试网络与 5xx 错误。服务端将数据库变更与幂等响应放在同一事务；重放返回 Idempotency-Replayed: true。相同键且正文不同返回 409 IDEMPOTENCY_CONFLICT；RETRY_IN_PROGRESS 按 2/4/8 秒退避，最多等待 120 秒后重试。网络错误和 5xx 可重试；429 应按 Retry-After 等待并复用原幂等键，其他 4xx 先修正输入。PATCH/DELETE 可重复执行；归档后再删返回 410。

## 限制与错误
单个素材 ≤ 32 MiB；封面 ≤ 4 MiB；请求 ≤ 38 MiB；请求正文读取限时 30 秒；multipart 文本字段（含 metadata JSON）每项 ≤ 64 KiB，最多 16 项；普通 JSON 正文 ≤ 1 MiB，Key 申请相关 JSON ≤ 16 KiB。媒体支持 PNG/JPEG/WebP/GIF/AVIF、MP4/WebM/MOV（浏览器播放兼容性由编码决定，推荐 H.264 MP4）。请为视频上传封面，并为大图提供小尺寸封面（建议最长边 800px）。图片未提供封面时回退到原图。音频支持 MP3、WAV、M4A、AAC、OGG/Opus、FLAC、WebM Audio（.weba），同样为 32 MiB 上限。音频详情提供播放器，兼容性取决于浏览器与实际编码；不能播放时仍可下载原文件。type=audio 可筛选，stats.audios 返回数量。未上传音频封面时提供默认唱片封面，也可通过封面接口替换。
ZIP ≤ 8 MB，最多 300 项，单文件解压 ≤ 4 MB，总解压 ≤ 24 MB；必须包含 SKILL.md；拒绝路径穿越、软链接、加密、多卷和高压缩比异常包。不执行包内脚本。
分页 limit 为 1–100，offset ≥ 0；排序稳定使用时间与 ID。并发新增时 offset 分页可能移动，长时间同步建议按稳定 ID 去重。
错误统一为 {"error":{"code":"VALIDATION_ERROR","message":"可读说明","details":null,"request_id":"..."}}。常见状态：400 请求格式或幂等键缺失；401 未授权；403 权限不足；404 不存在；409 引用/版本/重试冲突；410 已归档；413 文件过大；415 不支持类型；422 字段或 ZIP 无效；429 限流或并发过载（Retry-After）；500 可重试服务错误。