{"openapi":"3.0.3","info":{"title":"AIFather Material Library API","version":"1.4.0","description":"公开读取，授权写入。生成由外部 Agent 自身工具完成，本站保存结果及不可变出处。所有 POST 需要幂等键。"},"servers":[{"url":"https://www.aifather.art/api/v1"}],"paths":{"/assets":{"get":{"operationId":"get__assets","summary":"分页搜索素材摘要（只读已保存元数据，不逐文件解析）","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","enum":["image","video","audio"]}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"project_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}},{"name":"visibility","in":"query","schema":{"type":"string","enum":["public","private","all"],"default":"public"},"description":"private/all 需要管理员或 private:read"}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetPage"}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"},"post":{"operationId":"post__assets","summary":"上传素材，可原子保存生成记录","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":150},"description":"重试复用同一键、文件内容与字段值；multipart boundary 可变化"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"cover":{"type":"string","format":"binary"},"metadata":{"type":"string","description":"JSON 编码的 AssetInput，≤ 64 KiB。原文件 ≤ 32 MiB，封面 ≤ 4 MiB，请求 ≤ 38 MiB，正文读取限时 30 秒。客户端媒体字段仅为声明。"}}}}}},"responses":{"201":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetUploadResult"}}}},"429":{"description":"限流或并发过载；按 Retry-After 等待并复用同一 Idempotency-Key","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"等待秒数"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"认证主体每分钟最多 12 次；所有 multipart 上传（含 Skill/封面）与重新验证共享全站最多 1 个在途操作的租约，崩溃租约 90 秒过期。没有吞吐保证或异步队列。媒体头/容器解析不是完整解码或安全扫描。"}},"/assets/{id}":{"get":{"operationId":"get__assets__id_","summary":"素材详情，按需展开历史","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"},"patch":{"operationId":"patch__assets__id_","summary":"编辑当前信息、配置及参考关系","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetInput"}}}},"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"delete__assets__id_","summary":"归档素材并保留历史","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"confirm","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets/{id}/verify-metadata":{"post":{"operationId":"post__assets__id__verify_metadata","summary":"库主或 assets:write Key 显式重新验证单个素材的媒体元数据","security":[{"siteSession":[]},{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":150},"description":"重试复用同一键、文件内容与字段值；multipart boundary 可变化"}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetVerificationResult"}}}},"429":{"description":"限流或并发过载；按 Retry-After 等待并复用同一 Idempotency-Key","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"等待秒数"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"权限与编辑素材一致：库主或现有 assets:write Key；私有素材还需 private:read。无需新凭证或扩展持久授权。原文件 ≤ 32 MiB，解析预算 32 MiB。只保存媒体元数据及 SHA-256，不改文件、提示词、不可变历史或公开/私有归属。不支持批量操作或异步队列。原文件无效时保存 invalid 状态和哈希，未知媒体字段为 null。"}},"/assets/{id}/replace-original":{"post":{"operationId":"post__assets__id__replace_original","summary":"原子替换已有图片原文件，保留稳定 ID 和创作元数据","security":[{"siteSession":[]},{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":150},"description":"重试复用同一键、文件内容与字段值；multipart boundary 可变化"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":false,"required":["file","expected_sha256","expected_updated_at"],"properties":{"file":{"type":"string","format":"binary"},"expected_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"expected_updated_at":{"type":"string","format":"date-time"},"cover_policy":{"type":"string","enum":["preserve","original"],"default":"preserve"}}}}}},"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"限流或并发过载；按 Retry-After 等待并复用同一 Idempotency-Key","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"等待秒数"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"需要 assets:write；私有素材另需 private:read。预条件来自当前详情。32 MiB 文件、38 MiB 请求、30 秒正文限制；复用上传限流和租约。仅接受可验证图片。保留旧原图；相同哈希为无操作，过期预条件返回 409。自定义封面默认保留，明确 original 才切换原图预览。"}},"/assets/{id}/originals":{"get":{"operationId":"get__assets__id__originals","summary":"读取保留的原图备份列表；仅库主或 assets:write + private:read","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"}},"/assets/{id}/originals/{replacement_id}/file":{"get":{"operationId":"get__assets__id__originals__replacement_id__file","summary":"下载旧原图以恢复；仅库主或 assets:write + private:read","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"replacement_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"}},"/assets/{id}/references":{"get":{"operationId":"get__assets__id__references","summary":"读取入向引用计数","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"}},"/assets/{id}/generations":{"get":{"operationId":"get__assets__id__generations","summary":"分页读取不可变生成记录","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"},"post":{"operationId":"post__assets__id__generations","summary":"保存实际生成快照","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":150},"description":"重试复用同一键、文件内容与字段值；multipart boundary 可变化"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}}},"responses":{"201":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets/{id}/cover":{"post":{"operationId":"post__assets__id__cover","summary":"更新封面","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":150},"description":"重试复用同一键、文件内容与字段值；multipart boundary 可变化"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"only_if_missing":{"type":"boolean","default":false},"expected_updated_at":{"type":"string","format":"date-time","description":"Required with only_if_missing=true; from the latest asset detail"}}}}}},"responses":{"201":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"get__assets__id__cover","summary":"读取当前封面","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"二进制文件","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"字节范围响应"},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"}},"/assets/{id}/file":{"get":{"operationId":"get__assets__id__file","summary":"下载原文件，支持 HTTP Range","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"download","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"二进制文件","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"字节范围响应"},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"}},"/skills":{"get":{"operationId":"get__skills","summary":"分页搜索 Skill 摘要","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}},{"name":"visibility","in":"query","schema":{"type":"string","enum":["public","private","all"],"default":"public"},"description":"private/all 需要管理员或 private:read"}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"},"post":{"operationId":"post__skills","summary":"上传安全检查后的 Skill ZIP","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":150},"description":"重试复用同一键、文件内容与字段值；multipart boundary 可变化"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"cover":{"type":"string","format":"binary"},"metadata":{"type":"string","description":"JSON 字符串 {name,description,version,visibility?}，visibility 默认 public"}}}}}},"responses":{"201":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/skills/{id}":{"get":{"operationId":"get__skills__id_","summary":"Skill 文件树及版本","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"version_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"},"patch":{"operationId":"patch__skills__id_","summary":"修改 Skill 名称与介绍","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"visibility":{"type":"string","enum":["public","private"],"default":"public","description":"创建时确定；修改返回 VISIBILITY_FIXED"}}}}}},"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"delete__skills__id_","summary":"归档 Skill，保留历史版本","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"confirm","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/skills/{id}/versions":{"post":{"operationId":"post__skills__id__versions","summary":"通过编辑文本或上传 ZIP 创建新版本","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":150},"description":"重试复用同一键、文件内容与字段值；multipart boundary 可变化"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["base_version_id","path","content","version"],"properties":{"base_version_id":{"type":"string"},"path":{"type":"string"},"content":{"type":"string"},"version":{"type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","required":["file","metadata"],"properties":{"file":{"type":"string","format":"binary"},"metadata":{"type":"string","description":"JSON 字符串 {version}"}}}}}},"responses":{"201":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/skills/{id}/files/{path}":{"get":{"operationId":"get__skills__id__files__path_","summary":"读取完整 Skill 引用文件","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"path","required":true,"schema":{"type":"string"},"description":"保留目录分隔，每个路径段分别编码"},{"name":"version_id","in":"query","schema":{"type":"string"}},{"name":"download","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"}},"/skills/{id}/download":{"get":{"operationId":"get__skills__id__download","summary":"完整版本 ZIP 下载","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"version_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"二进制文件","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"字节范围响应"},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"}},"/projects":{"get":{"operationId":"get__projects","summary":"分页搜索片子 / 项目","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}},{"name":"visibility","in":"query","schema":{"type":"string","enum":["public","private","all"],"default":"public"},"description":"private/all 需要管理员或 private:read"}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"},"post":{"operationId":"post__projects","summary":"创建片子 / 项目","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":150},"description":"重试复用同一键、文件内容与字段值；multipart boundary 可变化"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"visibility":{"type":"string","enum":["public","private"],"default":"public","description":"创建时确定；修改返回 VISIBILITY_FIXED"}}}}}},"responses":{"201":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{id}":{"get":{"operationId":"get__projects__id_","summary":"项目详情及素材入口","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"},"patch":{"operationId":"patch__projects__id_","summary":"编辑片子 / 项目","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"visibility":{"type":"string","enum":["public","private"],"default":"public","description":"创建时确定；修改返回 VISIBILITY_FIXED"}}}}}},"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"delete__projects__id_","summary":"归档项目，保留素材","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/session":{"get":{"operationId":"get__session","summary":"当前会话写权限","security":[],"parameters":[],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats":{"get":{"operationId":"get__stats","summary":"素材数量与标签","security":[{},{"bearerAuth":[]},{"siteSession":[]}],"parameters":[{"name":"visibility","in":"query","schema":{"type":"string","enum":["public","private","all"],"default":"public"},"description":"private/all 需要管理员或 private:read"}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"公开内容无需认证；私有内容需要管理员登录或带 private:read 的 Bearer Key。"}},"/tokens":{"get":{"operationId":"get__tokens","summary":"库主查看凭证列表","security":[{"siteSession":[]}],"parameters":[],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tokens/{id}":{"delete":{"operationId":"delete__tokens__id_","summary":"库主撤销历史 Agent 凭证","security":[{"siteSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/key-requests":{"get":{"operationId":"get__key_requests","summary":"本人申请列表；管理员可查看全部","security":[{"siteSession":[]}],"parameters":[{"name":"view","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"403":{"description":"非管理员审批、越权领取或跨域写操作"},"409":{"description":"revision 过期、状态不允许或并发冲突"},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"post__key_requests","summary":"公开提交 Key 申请；匿名申请需 request_secret","security":[],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":150},"description":"重试复用同一键、文件内容与字段值；multipart boundary 可变化"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","purpose","scopes"],"properties":{"name":{"type":"string","maxLength":100},"purpose":{"type":"string","maxLength":2000},"scopes":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["assets:write","skills:write","projects:write","private:read"]}},"request_secret":{"type":"string","pattern":"^[a-f0-9]{64}$","writeOnly":true,"description":"匿名申请必填；客户端安全生成并保存，服务端仅存哈希"}}}}}},"responses":{"201":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"非管理员审批、越权领取或跨域写操作"},"409":{"description":"revision 过期、状态不允许或并发冲突"},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/key-requests/{id}":{"get":{"operationId":"get__key_requests__id_","summary":"申请密钥持有人、已登录本人或管理员读取单条申请","security":[{"siteSession":[]},{"requestSecret":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"非管理员审批、越权领取或跨域写操作"},"409":{"description":"revision 过期、状态不允许或并发冲突"},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/key-requests/{id}/approve":{"post":{"operationId":"post__key_requests__id__approve","summary":"管理员审批并设置权限和有效期","security":[{"siteSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":150},"description":"重试复用同一键、文件内容与字段值；multipart boundary 可变化"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["revision","scopes"],"properties":{"revision":{"type":"integer","minimum":0},"scopes":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["assets:write","skills:write","projects:write","private:read"]}},"days":{"type":"integer","minimum":1,"maximum":365,"default":90},"note":{"type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"非管理员审批、越权领取或跨域写操作"},"409":{"description":"revision 过期、状态不允许或并发冲突"},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/key-requests/{id}/reject":{"post":{"operationId":"post__key_requests__id__reject","summary":"管理员拒绝申请","security":[{"siteSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":150},"description":"重试复用同一键、文件内容与字段值；multipart boundary 可变化"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["revision","note"],"properties":{"revision":{"type":"integer","minimum":0},"note":{"type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"非管理员审批、越权领取或跨域写操作"},"409":{"description":"revision 过期、状态不允许或并发冲突"},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/key-requests/{id}/claim":{"post":{"operationId":"post__key_requests__id__claim","summary":"申请人一次性领取；rotate=true 撤销旧 Key 后重新签发","security":[{"siteSession":[]},{"requestSecret":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":150},"description":"重试复用同一键、文件内容与字段值；multipart boundary 可变化"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["revision"],"properties":{"revision":{"type":"integer","minimum":0},"rotate":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"成功","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"request_id":{"type":"string"},"token":{"type":"string","description":"仅首次响应返回，幂等重放不含此字段"},"revision":{"type":"integer","minimum":0},"scopes":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["assets:write","skills:write","projects:write","private:read"]}},"expires_at":{"type":"string","format":"date-time"},"message":{"type":"string"}}}}}},"403":{"description":"非管理员审批、越权领取或跨域写操作"},"409":{"description":"revision 过期、状态不允许或并发冲突"},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/key-requests/{id}/revoke":{"post":{"operationId":"post__key_requests__id__revoke","summary":"本人或管理员撤销申请及其 Key","security":[{"siteSession":[]},{"requestSecret":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":150},"description":"重试复用同一键、文件内容与字段值；multipart boundary 可变化"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["revision"],"properties":{"revision":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"非管理员审批、越权领取或跨域写操作"},"409":{"description":"revision 过期、状态不允许或并发冲突"},"default":{"description":"结构化错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"requestSecret":{"type":"apiKey","in":"header","name":"X-Atelier-Request-Secret","description":"仅该匿名申请的本地保管密钥；不能审批、列举或访问素材。"},"siteSession":{"type":"apiKey","in":"header","name":"Cookie","description":"Sites 网页登录后浏览器自动携带的平台会话；管理员审批必须使用此会话；匿名申请查询/领取使用申请密钥；Agent Bearer Key 不能审批。Cookie 由平台管理，不要伪造身份头。"},"bearerAuth":{"type":"http","scheme":"bearer","description":"网站申请、管理员审批后由申请人领取。按资源范围授权，可过期和撤销。"}},"schemas":{"DeclaredMetadata":{"type":"object","additionalProperties":false,"description":"客户端声明，不是服务端检测值","properties":{"width":{"type":"integer","nullable":true},"height":{"type":"integer","nullable":true},"duration":{"type":"number","nullable":true,"description":"秒"},"codec":{"type":"string","nullable":true},"fps":{"type":"number","nullable":true},"has_audio":{"type":"boolean","nullable":true},"has_alpha":{"type":"boolean","nullable":true},"orientation":{"type":"integer","nullable":true}}},"MediaMetadata":{"type":"object","nullable":true,"description":"有界文件头/容器解析结果，不是完整解码或安全扫描；未知字段为 null","properties":{"width":{"type":"integer","nullable":true},"height":{"type":"integer","nullable":true},"duration":{"type":"number","nullable":true,"description":"秒"},"codec":{"type":"string","nullable":true},"fps":{"type":"number","nullable":true},"has_audio":{"type":"boolean","nullable":true},"has_alpha":{"type":"boolean","nullable":true},"orientation":{"type":"integer","nullable":true},"status":{"type":"string","enum":["verified","unverified","invalid"]},"source":{"type":"string","enum":["server_header_parser"]},"parser_version":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"mime":{"type":"string","nullable":true},"verified_fields":{"type":"array","items":{"type":"string"},"description":"仅这些字段被服务端解析确认；不表示完整解码或安全扫描"}}},"AssetVerificationResult":{"type":"object","properties":{"id":{"type":"string"},"sha256":{"type":"string","nullable":true,"pattern":"^[a-f0-9]{64}$","description":"服务端原文件 SHA-256；未计算的旧记录为 null，与字段验证状态独立"},"metadata_verified":{"type":"boolean","description":"有字段经服务端解析确认；请检查 verified_fields，不代表全部字段、可播放性或安全性"},"metadata_source":{"type":"string","enum":["server_header_parser","legacy_unverified"]},"metadata_status":{"type":"string","enum":["verified","unverified","invalid","legacy_unverified"]},"verified_fields":{"type":"array","items":{"type":"string"},"description":"仅这些字段被服务端解析确认；不表示完整解码或安全扫描"},"declared_metadata":{"$ref":"#/components/schemas/DeclaredMetadata"},"media_metadata":{"allOf":[{"$ref":"#/components/schemas/MediaMetadata"}],"nullable":true,"description":"旧记录未经解析时为 null"},"codec":{"type":"string","nullable":true},"fps":{"type":"number","nullable":true},"has_audio":{"type":"boolean","nullable":true},"has_alpha":{"type":"boolean","nullable":true},"orientation":{"type":"integer","nullable":true},"width":{"type":"integer","nullable":true,"description":"新上传仅服务端确认值；旧值标记 legacy_unverified"},"height":{"type":"integer","nullable":true,"description":"新上传仅服务端确认值；旧值标记 legacy_unverified"},"duration":{"type":"number","nullable":true,"description":"秒；新上传仅服务端确认值；旧值标记 legacy_unverified"}}},"AssetUploadResult":{"type":"object","properties":{"id":{"type":"string"},"visibility":{"type":"string","enum":["public","private"],"default":"public","description":"创建时确定；修改返回 VISIBILITY_FIXED"},"type":{"enum":["image","video","audio"]},"mime":{"type":"string"},"title":{"type":"string"},"detail_url":{"type":"string"},"api_url":{"type":"string"},"sha256":{"type":"string","nullable":true,"pattern":"^[a-f0-9]{64}$","description":"服务端原文件 SHA-256；未计算的旧记录为 null，与字段验证状态独立"},"metadata_verified":{"type":"boolean","description":"有字段经服务端解析确认；请检查 verified_fields，不代表全部字段、可播放性或安全性"},"metadata_source":{"type":"string","enum":["server_header_parser","legacy_unverified"]},"metadata_status":{"type":"string","enum":["verified","unverified","invalid","legacy_unverified"]},"verified_fields":{"type":"array","items":{"type":"string"},"description":"仅这些字段被服务端解析确认；不表示完整解码或安全扫描"},"declared_metadata":{"$ref":"#/components/schemas/DeclaredMetadata"},"media_metadata":{"allOf":[{"$ref":"#/components/schemas/MediaMetadata"}],"nullable":true,"description":"旧记录未经解析时为 null"},"codec":{"type":"string","nullable":true},"fps":{"type":"number","nullable":true},"has_audio":{"type":"boolean","nullable":true},"has_alpha":{"type":"boolean","nullable":true},"orientation":{"type":"integer","nullable":true},"width":{"type":"integer","nullable":true,"description":"新上传仅服务端确认值；旧值标记 legacy_unverified"},"height":{"type":"integer","nullable":true,"description":"新上传仅服务端确认值；旧值标记 legacy_unverified"},"duration":{"type":"number","nullable":true,"description":"秒；新上传仅服务端确认值；旧值标记 legacy_unverified"}}},"AssetPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"next_offset":{"type":"integer","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"nullable":true},"request_id":{"type":"string"}}}}},"Reference":{"type":"object","required":["asset_id","purpose"],"properties":{"asset_id":{"type":"string"},"purpose":{"type":"string"}}},"SkillRef":{"type":"object","required":["skill_id","version_id"],"properties":{"skill_id":{"type":"string"},"version_id":{"type":"string"}}},"Config":{"type":"object","properties":{"prompt":{"type":"string"},"negative_prompt":{"type":"string"},"parameters":{"type":"object","additionalProperties":true},"skills":{"type":"array","items":{"$ref":"#/components/schemas/SkillRef"}}}},"Generation":{"type":"object","required":["prompt","model","references","skills"],"properties":{"prompt":{"type":"string"},"negative_prompt":{"type":"string"},"model":{"type":"string"},"tool":{"type":"string"},"parameters":{"type":"object","additionalProperties":true},"notes":{"type":"string"},"references":{"type":"array","items":{"$ref":"#/components/schemas/Reference"}},"skills":{"type":"array","items":{"$ref":"#/components/schemas/SkillRef"}}}},"AssetInput":{"type":"object","properties":{"visibility":{"type":"string","enum":["public","private"],"default":"public","description":"创建时确定；修改返回 VISIBILITY_FIXED"},"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"project_ids":{"type":"array","items":{"type":"string"}},"width":{"type":"integer","nullable":true},"height":{"type":"integer","nullable":true},"duration":{"type":"number","nullable":true,"description":"秒"},"codec":{"type":"string","nullable":true},"fps":{"type":"number","nullable":true},"has_audio":{"type":"boolean","nullable":true},"has_alpha":{"type":"boolean","nullable":true},"orientation":{"type":"integer","nullable":true},"config":{"$ref":"#/components/schemas/Config"},"references":{"type":"array","items":{"$ref":"#/components/schemas/Reference"}},"generation":{"$ref":"#/components/schemas/Generation"}}},"Asset":{"type":"object","required":["id","title","type","created_at","updated_at","detail_url","original_url"],"properties":{"visibility":{"type":"string","enum":["public","private"],"default":"public","description":"创建时确定；修改返回 VISIBILITY_FIXED"},"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"type":{"enum":["image","video","audio"]},"mime":{"type":"string"},"filename":{"type":"string"},"size":{"type":"integer","description":"原文件字节数"},"sha256":{"type":"string","nullable":true,"pattern":"^[a-f0-9]{64}$","description":"服务端原文件 SHA-256；未计算的旧记录为 null，与字段验证状态独立"},"metadata_verified":{"type":"boolean","description":"有字段经服务端解析确认；请检查 verified_fields，不代表全部字段、可播放性或安全性"},"metadata_source":{"type":"string","enum":["server_header_parser","legacy_unverified"]},"metadata_status":{"type":"string","enum":["verified","unverified","invalid","legacy_unverified"]},"verified_fields":{"type":"array","items":{"type":"string"},"description":"仅这些字段被服务端解析确认；不表示完整解码或安全扫描"},"declared_metadata":{"$ref":"#/components/schemas/DeclaredMetadata"},"media_metadata":{"allOf":[{"$ref":"#/components/schemas/MediaMetadata"}],"nullable":true,"description":"旧记录未经解析时为 null"},"codec":{"type":"string","nullable":true},"fps":{"type":"number","nullable":true},"has_audio":{"type":"boolean","nullable":true},"has_alpha":{"type":"boolean","nullable":true},"orientation":{"type":"integer","nullable":true},"width":{"type":"integer","nullable":true,"description":"新上传仅服务端确认值；旧值标记 legacy_unverified"},"height":{"type":"integer","nullable":true,"description":"新上传仅服务端确认值；旧值标记 legacy_unverified"},"duration":{"type":"number","nullable":true,"description":"秒；新上传仅服务端确认值；旧值标记 legacy_unverified"},"tags":{"type":"array","items":{"type":"string"}},"project_ids":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"deleted_at":{"type":"string","nullable":true},"detail_url":{"type":"string","format":"uri"},"api_url":{"type":"string","format":"uri"},"original_url":{"type":"string","format":"uri"},"download_url":{"type":"string","format":"uri"},"cover_url":{"type":"string","format":"uri","nullable":true},"has_custom_cover":{"type":"boolean"},"preview_kind":{"enum":["cover","small_original","audio_placeholder","missing"]},"config":{"$ref":"#/components/schemas/Config"},"references":{"type":"array","items":{"type":"object","additionalProperties":true}},"generations_url":{"type":"string"}}},"Skill":{"type":"object","properties":{"visibility":{"type":"string","enum":["public","private"],"default":"public","description":"创建时确定；修改返回 VISIBILITY_FIXED"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"version_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"detail_url":{"type":"string"},"download_url":{"type":"string"},"selected_version":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"string"},"created_at":{"type":"string"},"download_url":{"type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"size":{"type":"integer"},"text":{"type":"boolean"},"sha256":{"type":"string"},"url":{"type":"string"}}}}}},"versions":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"Page":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"next_offset":{"type":"integer","nullable":true}}}}},"externalDocs":{"description":"完整 Agent 操作说明","url":"https://www.aifather.art/api/v1/agent-guide"}}