{"openapi":"3.1.0","info":{"title":"Relay · 统一自动发布中心","description":"为业务网站集中管理抖音、快手和小红书的账号、素材与异步发布任务。\n\n## 接入顺序\n\n1. 管理员创建接入项目、授权平台账号并完成登录。\n2. 业务服务使用项目 API 密钥调用 `GET /v1/accounts`，获取已授权账号。\n3. 调用 `POST /v1/assets` 上传素材，保存返回的素材 ID。\n4. 调用 `POST /v1/publish-jobs` 提交发布批次，并保存批次 ID。\n5. 查询批次 / 子任务，或接收经过 HMAC-SHA256 验签的 Webhook。\n\n## 鉴权与边界\n\n业务接口使用 `Authorization: Bearer <项目 API 密钥>`。每个项目只能访问自己的素材与任务、已获授权的账号。\n管理接口 `/api/admin/*` 使用管理员令牌。项目密钥与 Webhook 密钥只在创建项目时一起返回；\n项目 API 密钥轮换后旧密钥立即失效。密钥应保存在业务服务端。\n\n## 异步与幂等\n\nHTTP 202 表示任务已接收。`submitted` 表示平台受理，`scheduled` 表示已设置平台预约，均不代表已公开。\n同一项目内，相同 `idempotency_key` 和相同内容返回原批次；同键不同内容返回 409。\n请求超时时请保留原键和原请求重试。`submission_unknown` 必须先核实平台作品，再由管理员处理。\n\n## 时间与回调\n\n`publish_at` 必须包含时区；返回时间使用 UTC，后台显示北京时间。\n`immediate` 尽快执行；`platform` 提前上传并设置平台定时（需提前大于两小时）；\n`server` 到点才开始上传，公开时间仍取决于上传和审核。\nWebhook 至少投递一次，可能重复或乱序；使用事件 ID 去重，并按任务 ID 与版本处理新旧状态。","version":"0.1.0"},"paths":{"/api/admin/overview":{"get":{"tags":["管理 · 运维"],"summary":"查看运行概览","description":"返回项目、账号、素材、任务计数及最近 12 条任务。worker_alive 根据共享目录中的心跳文件判断，90 秒内更新为在线；不等同于真实平台发布验收通过。","operationId":"overview_api_admin_overview_get","responses":{"200":{"description":"运行概览；计数与心跳均为结构示例。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"counts":{"jobs":1,"accounts":1,"projects":1,"assets":1,"queued":1,"running":0,"needs_attention":0},"recent_jobs":[{"id":"job_example","batch_id":"batch_example","project_id":"prj_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"publish","content_type":"video","title":"秋日旅行记录","status":"queued","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":1,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}],"adapter_mode":"browser","worker_alive":true,"worker_last_seen":"2026-10-27T02:00:00+00:00"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"}},"security":[{"HTTPBearer":[]}]}},"/api/admin/projects":{"get":{"tags":["管理 · 项目"],"summary":"列出接入项目","description":"按创建时间倒序返回所有项目和账号授权列表。已有项目的 API 密钥与 Webhook 密钥不再返回。","operationId":"list_projects_api_admin_projects_get","responses":{"200":{"description":"项目列表（不含密钥）。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":[{"id":"prj_example","name":"品牌内容站","enabled":true,"callback_url":"https://example.com/webhooks/publisher","created_at":"2026-10-26T02:00:00+00:00","account_ids":["acc_example"]}]}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["管理 · 项目"],"summary":"创建项目与接入凭证","description":"创建一个独立业务项目，返回 project、api_key 和 webhook_secret。两种密钥请在此时安全保存。callback_url 可选，默认仅接受可解析的公网 HTTP(S) 地址且不得带用户名、密码或 URL 片段。","operationId":"create_project_api_admin_projects_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectCreate"}}},"required":true},"responses":{"201":{"description":"项目已创建；凭证仅此时返回，以下为不可用占位值。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"project":{"id":"prj_example","name":"品牌内容站","enabled":true,"callback_url":"https://example.com/webhooks/publisher","created_at":"2026-10-26T02:00:00+00:00","account_ids":[]},"api_key":"pc_REPLACE_WITH_PROJECT_API_KEY","webhook_secret":"REPLACE_WITH_WEBHOOK_SECRET"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"422":{"description":"字段格式、业务规则、平台内容限制或时间校验失败。查看 detail 获取原因。"}},"security":[{"HTTPBearer":[]}]}},"/api/admin/projects/{project_id}":{"patch":{"tags":["管理 · 项目"],"summary":"修改项目设置","description":"仅修改请求中出现的字段。可改名称、启停项目或回调地址；callback_url 传 null 或空字符串可关闭回调。停用后项目 API 密钥不能通过鉴权。","operationId":"patch_project_api_admin_projects__project_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","title":"Project Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectPatch"}}}},"responses":{"200":{"description":"项目当前设置。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"prj_example","name":"品牌内容站","enabled":true,"callback_url":"https://example.com/webhooks/publisher","created_at":"2026-10-26T02:00:00+00:00","account_ids":["acc_example"]}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"422":{"description":"字段格式、业务规则、平台内容限制或时间校验失败。查看 detail 获取原因。"}}}},"/api/admin/projects/{project_id}/rotate-key":{"post":{"tags":["管理 · 项目"],"summary":"轮换项目 API 密钥","description":"立即生成并返回新 api_key，旧密钥失效。此操作不轮换 webhook_secret。更新业务服务端保存的凭证后继续请求。","operationId":"rotate_project_key_api_admin_projects__project_id__rotate_key_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","title":"Project Id"}}],"responses":{"200":{"description":"新密钥仅此时返回；以下为不可用占位值。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"api_key":"pc_REPLACE_WITH_NEW_PROJECT_API_KEY"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/projects/{project_id}/accounts":{"put":{"tags":["管理 · 项目"],"summary":"替换项目的账号授权","description":"以 account_ids 完整替换原有授权，不是追加。传空数组会撤销全部账号授权；所有账号 ID 必须存在。","operationId":"set_grants_api_admin_projects__project_id__accounts_put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","title":"Project Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantsInput"}}}},"responses":{"200":{"description":"项目与替换后的完整账号授权列表。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"prj_example","name":"品牌内容站","enabled":true,"callback_url":"https://example.com/webhooks/publisher","created_at":"2026-10-26T02:00:00+00:00","account_ids":["acc_example"]}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/accounts":{"get":{"tags":["管理 · 账号"],"summary":"列出全部平台账号","description":"返回所有账号，包括停用账号、浏览器环境、会话状态和当前占用情况。","operationId":"list_accounts_api_admin_accounts_get","responses":{"200":{"description":"全部账号列表；管理端包含 environment。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":[{"id":"acc_example","platform":"xiaohongshu","name":"品牌小红书账号","platform_uid":"platform_user_example","enabled":true,"status":"active","last_verified_at":"2026-10-27T02:00:00+00:00","busy":false,"created_at":"2026-10-26T02:00:00+00:00","environment":{"locale":"zh-CN","timezone_id":"Asia/Shanghai","viewport":{"width":1440,"height":900}}}]}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["管理 · 账号"],"summary":"添加平台账号","description":"创建抖音、快手或小红书账号记录与独立环境配置。创建成功不代表登录成功；随后发起登录，并为项目授予账号权限。浏览器档案不保证会话永不过期。","operationId":"create_account_api_admin_accounts_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountCreate"}}},"required":true},"responses":{"201":{"description":"账号已创建，尚未登录。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"acc_example","platform":"xiaohongshu","name":"品牌小红书账号","enabled":true,"status":"needs_login","busy":false,"created_at":"2026-10-26T02:00:00+00:00","environment":{"locale":"zh-CN","timezone_id":"Asia/Shanghai","viewport":{"width":1440,"height":900}}}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"422":{"description":"字段格式、业务规则、平台内容限制或时间校验失败。查看 detail 获取原因。"}},"security":[{"HTTPBearer":[]}]}},"/api/admin/accounts/{account_id}":{"patch":{"tags":["管理 · 账号"],"summary":"修改账号名称与启停状态","description":"仅修改已提供的字段。停用时状态为 disabled；重新启用时设为 needs_login，需重新检查或登录。此接口不修改平台、环境或账号档案。","operationId":"patch_account_api_admin_accounts__account_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string","title":"Account Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPatch"}}}},"responses":{"200":{"description":"修改后的账号；示例为重新启用并等待登录。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"acc_example","platform":"xiaohongshu","name":"品牌小红书账号","platform_uid":"platform_user_example","enabled":true,"status":"needs_login","last_verified_at":"2026-10-27T02:00:00+00:00","busy":false,"created_at":"2026-10-26T02:00:00+00:00","environment":{"locale":"zh-CN","timezone_id":"Asia/Shanghai","viewport":{"width":1440,"height":900}}}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"422":{"description":"字段格式、业务规则、平台内容限制或时间校验失败。查看 detail 获取原因。"}}}},"/api/admin/accounts/{account_id}/login":{"post":{"tags":["管理 · 账号"],"summary":"发起账号登录","description":"异步创建登录子任务并返回 HTTP 202；同账号已有待执行 / 执行中 / 等待验证的登录任务时复用。通过任务详情和人工验证接口处理二维码或短信；需要独立 Worker 执行。","operationId":"login_account_api_admin_accounts__account_id__login_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string","title":"Account Id"}}],"responses":{"202":{"description":"登录任务已入队或返回已有同类活跃任务。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"job_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"login","title":"","status":"queued","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":1,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"409":{"description":"当前状态不允许操作，或相同幂等键对应了不同请求。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/accounts/{account_id}/check":{"post":{"tags":["管理 · 账号"],"summary":"检查账号登录态","description":"异步检查账号已有浏览器会话，返回 HTTP 202。已有同类活跃任务时复用。结果以任务状态为准，202 不表示登录态有效。","operationId":"check_account_api_admin_accounts__account_id__check_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string","title":"Account Id"}}],"responses":{"202":{"description":"检查任务已入队或返回已有同类活跃任务。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"job_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"check","title":"","status":"queued","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":1,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"409":{"description":"当前状态不允许操作，或相同幂等键对应了不同请求。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/jobs":{"get":{"tags":["管理 · 任务"],"summary":"筛选与查询全部子任务","description":"按状态、平台或项目筛选，按创建时间倒序返回。默认最多 200 条，可设置 1–500；没有页码或游标。包含发布、登录和检查任务。","operationId":"list_jobs_api_admin_jobs_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform"}},{"name":"project_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"返回记录上限；按创建时间倒序，无分页游标。","default":200,"title":"Limit"},"description":"返回记录上限；按创建时间倒序，无分页游标。"}],"responses":{"200":{"description":"按筛选条件返回的最近子任务列表。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":[{"id":"job_example","batch_id":"batch_example","project_id":"prj_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"publish","content_type":"video","title":"秋日旅行记录","status":"queued","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":1,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}]}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/jobs/{job_id}":{"get":{"tags":["管理 · 任务"],"summary":"查看任务详情与诊断记录","description":"返回 job、按版本排序的 events、绑定的 challenges、诊断图片 artifacts 及发布 content。适用于检查失败原因、登录验证和提交边界。","operationId":"job_details_api_admin_jobs__job_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"任务、事件、验证、诊断图片和内容；示例为登录中等待扫码。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"job":{"id":"job_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"login","title":"","status":"waiting_verification","phase":"preflight","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":1,"result":{},"version":3,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"},"events":[{"id":"evt_queued_example","version":1,"status":"queued","message":"等待账号操作","created_at":"2026-10-27T02:00:00+00:00"},{"id":"evt_running_example","version":2,"status":"running","message":"已取得账号执行锁，开始处理","created_at":"2026-10-27T02:00:01+00:00"},{"id":"evt_verification_example","version":3,"status":"waiting_verification","message":"等待管理员完成账号验证","created_at":"2026-10-27T02:00:02+00:00"}],"challenges":[{"id":"chl_example","account_id":"acc_example","job_id":"job_example","kind":"qr","status":"pending","message":"请使用对应平台手机客户端扫描二维码完成登录。","expires_at":"2026-10-27T02:05:00+00:00","created_at":"2026-10-27T02:00:00+00:00","image_url":"/api/admin/challenges/chl_example/image"}],"artifacts":[{"name":"login-state.png","url":"/api/admin/jobs/job_example/artifacts/login-state.png"}],"content":{}}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["管理 · 任务"],"summary":"编辑未提交子任务","description":"仅可修改 queued / failed 且明确未提交的发布任务。允许修改标题、正文及已有定时任务的时间，至少提供一个非 null 字段；仍按平台内容限制校验。失败任务保存后仍为 failed，需明确调用重试。","operationId":"admin_edit_job_api_admin_jobs__job_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPatch"}}}},"responses":{"200":{"description":"内容已保存；原状态保持不变。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"job_example","batch_id":"batch_example","project_id":"prj_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"publish","content_type":"video","title":"更新后的旅行记录","status":"queued","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":2,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"409":{"description":"当前状态不允许操作，或相同幂等键对应了不同请求。"},"422":{"description":"字段格式、业务规则、平台内容限制或时间校验失败。查看 detail 获取原因。"}}}},"/api/admin/jobs/{job_id}/artifacts":{"get":{"tags":["管理 · 任务"],"summary":"列出任务诊断图片","description":"返回该任务的 PNG、JPG、JPEG、WebP 诊断图片名称与受鉴权保护的下载地址；无图片时返回空数组。","operationId":"list_job_artifacts_api_admin_jobs__job_id__artifacts_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"诊断图片列表；下载仍需管理员鉴权。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":[{"name":"login-state.png","url":"/api/admin/jobs/job_example/artifacts/login-state.png"}]}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/jobs/{job_id}/artifacts/{filename}":{"get":{"tags":["管理 · 任务"],"summary":"下载任务诊断图片","description":"返回单张诊断图片。文件必须位于当前任务的诊断目录并属于支持的图片类型；不存在时返回 404。","operationId":"get_job_artifact_api_admin_jobs__job_id__artifacts__filename__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"filename","in":"path","required":true,"schema":{"type":"string","title":"Filename"}}],"responses":{"200":{"description":"文件内容（非 JSON）","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/jobs/{job_id}/cancel":{"post":{"tags":["管理 · 任务"],"summary":"取消一个本地子任务","description":"仅取消未被执行进程占用、明确尚未提交的 queued / waiting_login / failed 任务；已取消任务可再次调用。已提交、正在提交或结果待核实任务返回 409。不能取消平台已受理的作品。","operationId":"admin_cancel_api_admin_jobs__job_id__cancel_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"本地子任务已取消。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"job_example","batch_id":"batch_example","project_id":"prj_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"publish","content_type":"video","title":"秋日旅行记录","status":"cancelled","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":2,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"409":{"description":"当前状态不允许操作，或相同幂等键对应了不同请求。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/jobs/{job_id}/retry":{"post":{"tags":["管理 · 任务"],"summary":"重试明确未提交的失败任务","description":"仅允许未被占用且未越过提交边界的 failed 任务。账号须启用，发布任务的项目与账号授权仍须有效。服务器定时的手工重试始终立即入队，不再等待 publish_at，即使该时间已改到未来。如需延期，先核实原任务未提交并取消，确认不会再执行后再建立新排期；不得换键绕过未核实结果。平台定时仍须满足提前量要求。","operationId":"admin_retry_api_admin_jobs__job_id__retry_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"明确未提交的失败任务已重新入队。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"job_example","batch_id":"batch_example","project_id":"prj_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"publish","content_type":"video","title":"秋日旅行记录","status":"queued","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":4,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"409":{"description":"当前状态不允许操作，或相同幂等键对应了不同请求。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/jobs/{job_id}/resolve":{"post":{"tags":["管理 · 任务"],"summary":"记录提交结果的人工核实结论","description":"仅处理停止执行的 submission_unknown 任务。先到平台核对原作品，再记录 submitted、scheduled 或 failed 及核实说明。只有确认平台未收到作品时才选择 failed，随后才可安全重试。","operationId":"resolve_job_api_admin_jobs__job_id__resolve_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveInput"}}}},"responses":{"200":{"description":"已记录管理员核实的平台受理结果。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"job_example","batch_id":"batch_example","project_id":"prj_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"publish","content_type":"video","title":"秋日旅行记录","status":"submitted","phase":"submitted","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":1,"result":{"manual_resolution":"已在平台作品管理页核对，作品已受理。"},"version":5,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"409":{"description":"当前状态不允许操作，或相同幂等键对应了不同请求。"},"422":{"description":"字段格式、业务规则、平台内容限制或时间校验失败。查看 detail 获取原因。"}}}},"/api/admin/challenges":{"get":{"tags":["管理 · 人工验证"],"summary":"列出待处理人工验证","description":"返回最近 100 条 pending / answered 验证请求。每条记录绑定账号与任务，包含类型、有效期和可选图片地址。","operationId":"list_challenges_api_admin_challenges_get","responses":{"200":{"description":"待处理或已回答的验证请求列表。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":[{"id":"chl_example","account_id":"acc_example","job_id":"job_example","kind":"qr","status":"pending","message":"请使用对应平台手机客户端扫描二维码完成登录。","expires_at":"2026-10-27T02:05:00+00:00","created_at":"2026-10-27T02:00:00+00:00","image_url":"/api/admin/challenges/chl_example/image"}]}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"}},"security":[{"HTTPBearer":[]}]}},"/api/admin/challenges/{challenge_id}/image":{"get":{"tags":["管理 · 人工验证"],"summary":"查看验证二维码或图片","description":"下载当前验证请求的图片。无图片或文件丢失返回 404；超过 expires_at 返回 410。图片受管理员鉴权保护。","operationId":"challenge_image_api_admin_challenges__challenge_id__image_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"challenge_id","in":"path","required":true,"schema":{"type":"string","title":"Challenge Id"}}],"responses":{"200":{"description":"文件内容（非 JSON）","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"410":{"description":"验证图片已过期。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/challenges/{challenge_id}/response":{"post":{"tags":["管理 · 人工验证"],"summary":"提交人工验证响应","description":"仅接受尚未过期、状态为 pending 且绑定任务仍在执行的请求。sms 响应必须是 4–8 位数字；sms_request 必须传 send_sms。其他类型按验证请求提示提交。验证响应加密保存，提交响应不表示验证最终通过。","operationId":"answer_challenge_api_admin_challenges__challenge_id__response_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"challenge_id","in":"path","required":true,"schema":{"type":"string","title":"Challenge Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChallengeResponse"}}}},"responses":{"200":{"description":"验证响应已保存，等待执行进程继续处理。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"chl_example","account_id":"acc_example","job_id":"job_example","kind":"sms","status":"answered","message":"请填写平台发送的短信验证码。","expires_at":"2026-10-27T02:05:00+00:00","created_at":"2026-10-27T02:00:00+00:00"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"409":{"description":"当前状态不允许操作，或相同幂等键对应了不同请求。"},"422":{"description":"字段格式、业务规则、平台内容限制或时间校验失败。查看 detail 获取原因。"}}}},"/api/admin/assets":{"get":{"tags":["管理 · 素材"],"summary":"查询项目素材","description":"按创建时间倒序返回最近 300 条素材，可通过 project_id 筛选。返回受管理员鉴权保护的文件地址，不暴露服务器磁盘路径。","operationId":"list_assets_api_admin_assets_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id"}}],"responses":{"200":{"description":"素材列表；示例下载地址使用管理接口。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":[{"id":"ast_example","project_id":"prj_example","filename":"cover.png","media_type":"image/png","size":82416,"sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","created_at":"2026-10-27T02:00:00+00:00","url":"/api/admin/assets/ast_example/file"}]}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["管理 · 素材"],"summary":"为指定项目上传素材","description":"使用 multipart/form-data，传入 project_id 和单个 file。项目须存在并启用。格式、大小、磁盘空间限制与业务上传接口相同。","operationId":"admin_upload_api_admin_assets_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_admin_upload_api_admin_assets_post"}}}},"responses":{"201":{"description":"素材已保存到指定项目。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"ast_example","project_id":"prj_example","filename":"cover.png","media_type":"image/png","size":82416,"sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","created_at":"2026-10-27T02:00:00+00:00","url":"/api/admin/assets/ast_example/file"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"413":{"description":"文件或 multipart 请求超过服务配置的上传上限。"},"422":{"description":"字段格式、业务规则、平台内容限制或时间校验失败。查看 detail 获取原因。"},"503":{"description":"真实浏览器模式所需的视频检测工具 ffprobe 未安装。"},"507":{"description":"接收临时盘或素材存储盘空间不足 / 暂不可用，请清理或扩容后重试。"}}}},"/api/admin/assets/{asset_id}/file":{"get":{"tags":["管理 · 素材"],"summary":"下载任意项目的素材","description":"以管理员权限下载素材原文件；文件不存在时返回 404，响应按素材 media_type 返回。","operationId":"admin_asset_file_api_admin_assets__asset_id__file_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","title":"Asset Id"}}],"responses":{"200":{"description":"文件内容（非 JSON）","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/publish-jobs":{"post":{"tags":["管理 · 任务"],"summary":"为指定项目创建发布批次","description":"管理员代发时必须指定 project_id；其他参数、幂等与平台校验语义同业务创建批次接口。该项目仍须拥有目标账号和全部素材。202 仅表示已接收，必须后续查询子任务结果。","operationId":"admin_publish_api_admin_publish_jobs_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminPublishInput"}}},"required":true},"responses":{"202":{"description":"指定项目的批次已接收；请继续查询子任务。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"batch_example","project_id":"prj_example","created_at":"2026-10-27T02:00:00+00:00","idempotency_key":"article-20261027-001","replayed":false,"jobs":[{"id":"job_example","batch_id":"batch_example","project_id":"prj_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"publish","content_type":"video","title":"秋日旅行记录","status":"queued","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":1,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}]}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"409":{"description":"当前状态不允许操作，或相同幂等键对应了不同请求。"},"422":{"description":"字段格式、业务规则、平台内容限制或时间校验失败。查看 detail 获取原因。"}},"security":[{"HTTPBearer":[]}]}},"/api/admin/settings":{"get":{"tags":["管理 · 运维"],"summary":"查看生效配置摘要","description":"返回适配模式、并发、超时、上传大小、空间保留量和调度参数等配置摘要，不包含密钥。通过部署环境变量修改后重启服务生效；mock 模式不执行真实发布。","operationId":"settings_view_api_admin_settings_get","responses":{"200":{"description":"生效配置摘要；数值使用代码默认配置作示例，以实际响应为准。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"adapter_mode":"browser","max_concurrency":2,"platform_concurrency_limit":1,"max_attempts":3,"job_timeout_seconds":1800,"verification_timeout_seconds":300,"max_upload_bytes":2147483648,"min_free_disk_bytes":2147483648,"asset_retention_days":30,"platform_schedule_lead_seconds":10800,"platform_schedule_horizon_days":7,"headless":true,"browser_channel":"chromium","account_check_interval_seconds":0,"account_publish_interval_seconds":60,"platforms":["douyin","kuaishou","xiaohongshu"],"timezone":"Asia/Shanghai","configuration":"部署环境变量配置，重启服务生效","session_guarantee":"登录态可能由平台撤销，需要人工恢复"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"}},"security":[{"HTTPBearer":[]}]}},"/api/admin/audit":{"get":{"tags":["管理 · 运维"],"summary":"查询操作审计","description":"按创建时间倒序返回最近 200 条审计记录，包含 action、subject_id、detail 和 created_at。","operationId":"audit_list_api_admin_audit_get","responses":{"200":{"description":"最近的审计记录。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":[{"id":"audit_example","action":"project.grants_updated","subject_id":"prj_example","detail":{"account_ids":["acc_example"]},"created_at":"2026-10-27T02:00:00+00:00"}]}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"}},"security":[{"HTTPBearer":[]}]}},"/api/admin/webhooks":{"get":{"tags":["管理 · Webhook"],"summary":"查询 Webhook 投递记录","description":"返回最近 200 条投递记录，包含事件 ID、任务版本、投递状态、尝试次数、错误与下次投递时间。投递失败不会重新执行发布。通知至少投递一次，接收方需去重并防止旧版本覆盖新状态。","operationId":"webhook_list_api_admin_webhooks_get","responses":{"200":{"description":"状态通知的投递记录；示例为尚未尝试的待投递事件。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":[{"id":"wh_example","project_id":"prj_example","job_id":"job_example","event_id":"evt_example","version":1,"status":"pending","attempts":0,"next_attempt_at":"2026-10-27T02:00:00+00:00","created_at":"2026-10-27T02:00:00+00:00"}]}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"}},"security":[{"HTTPBearer":[]}]}},"/api/admin/webhooks/{delivery_id}/retry":{"post":{"tags":["管理 · Webhook"],"summary":"重新投递一条 Webhook","description":"仅允许重试 pending / failed 投递记录，将尝试次数重置为 0 并重新入队。此操作仅发送状态通知，不会创建或重发平台作品。","operationId":"retry_webhook_api_admin_webhooks__delivery_id__retry_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"delivery_id","in":"path","required":true,"schema":{"type":"string","title":"Delivery Id"}}],"responses":{"200":{"description":"回调已重新入队；不重新发布作品。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"wh_example","status":"pending"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"409":{"description":"当前状态不允许操作，或相同幂等键对应了不同请求。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/accounts":{"get":{"tags":["账号"],"summary":"获取可用的授权账号","description":"列出当前项目已获授权且已启用的账号。使用返回的 id 作为 targets[].account_id；账号可能仍需登录或验证，enabled 不等于会话已就绪。响应不包含浏览器环境。管理员令牌调用时可见全部已启用账号。","operationId":"permitted_accounts_v1_accounts_get","responses":{"200":{"description":"已授权且启用的账号列表。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":[{"id":"acc_example","platform":"xiaohongshu","name":"品牌小红书账号","platform_uid":"platform_user_example","enabled":true,"status":"active","last_verified_at":"2026-10-27T02:00:00+00:00","busy":false,"created_at":"2026-10-26T02:00:00+00:00"}]}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"}},"security":[{"HTTPBearer":[]}]}},"/v1/assets":{"post":{"tags":["素材"],"summary":"上传图片或视频素材","description":"使用 multipart/form-data，字段名 file，每次上传一个文件。支持 JPG / JPEG、PNG、WebP、MP4、MOV、WebM、MKV、AVI；会检查实际格式。成功返回素材 id、类型、字节数、SHA-256 和下载地址。视频发布需一个视频素材，图文需一组图片；封面单独上传。单文件上限由 MAX_UPLOAD_BYTES 配置，默认 2 GiB，multipart 请求额外预留 1 MiB。超限返回 413；素材盘或临时盘可用空间不足返回 507，请管理员清理或扩容后再重试。浏览器模式上传视频需服务器安装 ffprobe，缺少时返回 503。业务网站需使用项目密钥，管理员上传请调用管理接口。","operationId":"public_upload_v1_assets_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_public_upload_v1_assets_post"}}},"required":true},"responses":{"201":{"description":"素材已保存；保存 id 供发布请求引用。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"ast_example","project_id":"prj_example","filename":"cover.png","media_type":"image/png","size":82416,"sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","created_at":"2026-10-27T02:00:00+00:00","url":"/v1/assets/ast_example/file"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"413":{"description":"文件或 multipart 请求超过服务配置的上传上限。"},"422":{"description":"字段格式、业务规则、平台内容限制或时间校验失败。查看 detail 获取原因。"},"503":{"description":"真实浏览器模式所需的视频检测工具 ffprobe 未安装。"},"507":{"description":"接收临时盘或素材存储盘空间不足 / 暂不可用，请清理或扩容后重试。"}},"security":[{"HTTPBearer":[]}]}},"/v1/assets/{asset_id}/file":{"get":{"tags":["素材"],"summary":"下载项目素材原文件","description":"仅能下载当前项目的素材。响应为文件流而非 JSON，不属于本项目或不存在的素材返回 404。下载时同样需要 Bearer 鉴权。","operationId":"public_asset_file_v1_assets__asset_id__file_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","title":"Asset Id"}}],"responses":{"200":{"description":"文件内容（非 JSON）","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/publish-jobs":{"get":{"tags":["发布任务"],"summary":"查询最近的发布批次","description":"返回当前项目最近 100 个批次，按创建时间倒序排列；每个批次包含 jobs 子任务数组。此接口没有页码或游标，需跟踪已知任务时请保存批次 ID 并按 ID 查询。","operationId":"list_batches_v1_publish_jobs_get","responses":{"200":{"description":"最近的发布批次。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":[{"id":"batch_example","project_id":"prj_example","created_at":"2026-10-27T02:00:00+00:00","idempotency_key":"article-20261027-001","replayed":false,"jobs":[{"id":"job_example","batch_id":"batch_example","project_id":"prj_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"publish","content_type":"video","title":"秋日旅行记录","status":"queued","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":1,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}]}]}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["发布任务"],"summary":"创建异步发布批次","description":"为 targets 中每个账号创建独立子任务，返回 HTTP 202 与批次 id、jobs、replayed。必须使用项目 API 密钥，全部素材须属于当前项目，目标账号须获授权且启用。相同项目内同幂等键、相同内容返回原批次并设 replayed=true；同键不同内容返回 409。请求超时使用原键和原请求重试。目标可覆盖 title / body / tags；多个目标按各自平台限制校验。immediate 尽快执行且不传 publish_at；platform 提前上传并设置平台原生定时，时间须大于当前两小时；server 到点才开始上传。所有时间必须含时区。202 不表示发布成功；submitted / scheduled 也不表示已公开。","operationId":"submit_publish_v1_publish_jobs_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishInput"}}},"required":true},"responses":{"202":{"description":"批次已接收；请查询 jobs 的后续状态。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"batch_example","project_id":"prj_example","created_at":"2026-10-27T02:00:00+00:00","idempotency_key":"article-20261027-001","replayed":false,"jobs":[{"id":"job_example","batch_id":"batch_example","project_id":"prj_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"publish","content_type":"video","title":"秋日旅行记录","status":"queued","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":1,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}]}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"409":{"description":"当前状态不允许操作，或相同幂等键对应了不同请求。"},"422":{"description":"字段格式、业务规则、平台内容限制或时间校验失败。查看 detail 获取原因。"}},"security":[{"HTTPBearer":[]}]}},"/v1/publish-jobs/{batch_id}":{"get":{"tags":["发布任务"],"summary":"查询一个批次及全部目标结果","description":"使用创建批次时返回的 id。jobs 内各目标独立变化，读取每条任务的 status、phase、error_code、error_message、result 和 version。submitted 表示平台受理；scheduled 表示预约已提交；submission_unknown 需管理员先核实平台作品。其他项目的批次返回 404。","operationId":"get_batch_v1_publish_jobs__batch_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","title":"Batch Id"}}],"responses":{"200":{"description":"批次与全部子任务的当前状态。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"batch_example","project_id":"prj_example","created_at":"2026-10-27T02:00:00+00:00","idempotency_key":"article-20261027-001","replayed":false,"jobs":[{"id":"job_example","batch_id":"batch_example","project_id":"prj_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"publish","content_type":"video","title":"秋日旅行记录","status":"queued","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":1,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}]}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["发布任务"],"summary":"修改所有目标均未执行的批次","description":"仅当批次全部目标均为 queued 且未被执行进程占用时可修改，否则返回 409。支持统一修改 title、body、已有定时任务的 publish_at；至少提供一个非 null 字段，不能把立即任务改成定时任务。按所有目标的平台限制重新校验，整批原子保存。修改内容会覆盖每个目标的对应字段。","operationId":"edit_batch_v1_publish_jobs__batch_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","title":"Batch Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPatch"}}}},"responses":{"200":{"description":"批次内容已更新。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"batch_example","project_id":"prj_example","created_at":"2026-10-27T02:00:00+00:00","idempotency_key":"article-20261027-001","replayed":false,"jobs":[{"id":"job_example","batch_id":"batch_example","project_id":"prj_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"publish","content_type":"video","title":"秋日旅行记录","status":"queued","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":1,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}]}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"409":{"description":"当前状态不允许操作，或相同幂等键对应了不同请求。"},"422":{"description":"字段格式、业务规则、平台内容限制或时间校验失败。查看 detail 获取原因。"}}}},"/v1/publish-jobs/{batch_id}/cancel":{"post":{"tags":["发布任务"],"summary":"取消批次中可安全取消的任务","description":"逐个处理 queued / waiting_login / failed 且明确未提交、未被执行进程占用的任务。HTTP 200 可能只是部分成功：请检查 cancelled_job_ids 与 skipped（含状态和原因）。已取消任务可重复调用；已提交或可能已提交的目标不会撤销。平台作品或平台预约需另到平台处理。","operationId":"cancel_batch_v1_publish_jobs__batch_id__cancel_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","title":"Batch Id"}}],"responses":{"200":{"description":"逐个目标取消结果；请检查 skipped。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"batch_example","project_id":"prj_example","created_at":"2026-10-27T02:00:00+00:00","idempotency_key":"article-20261027-001","replayed":false,"jobs":[{"id":"job_example","batch_id":"batch_example","project_id":"prj_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"publish","content_type":"video","title":"秋日旅行记录","status":"cancelled","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":2,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}],"cancelled_job_ids":["job_example"],"skipped":[]}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/publish-jobs/{batch_id}/retry":{"post":{"tags":["发布任务"],"summary":"重试批次中明确未提交的失败任务","description":"选取批次内 failed 子任务重新入队；没有失败任务返回 409。所有被选中的任务都必须明确未提交、未被占用且授权仍有效，否则本次重试整体不提交。submission_unknown 不在重试范围，须管理员核实。服务器定时的手工重试始终立即入队，不再等待 publish_at，即使该时间已改到未来。如需延期，先核实相关原任务未提交并取消，确认不会再执行后再建立新排期；不得换键绕过未核实结果。平台定时仍须满足提前量。","operationId":"retry_batch_v1_publish_jobs__batch_id__retry_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","title":"Batch Id"}}],"responses":{"200":{"description":"符合条件的失败任务已重新入队。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"batch_example","project_id":"prj_example","created_at":"2026-10-27T02:00:00+00:00","idempotency_key":"article-20261027-001","replayed":false,"jobs":[{"id":"job_example","batch_id":"batch_example","project_id":"prj_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"publish","content_type":"video","title":"秋日旅行记录","status":"queued","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":1,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}]}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"403":{"description":"项目、账号或素材无权限，或当前凭证没有管理员权限。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"409":{"description":"当前状态不允许操作，或相同幂等键对应了不同请求。"},"422":{"description":"字段格式、业务规则、平台内容限制或时间校验失败。查看 detail 获取原因。"}}}},"/v1/jobs/{job_id}":{"get":{"tags":["发布任务"],"summary":"查询一个子任务的状态","description":"使用 jobs[].id 查询单个目标。返回状态、阶段、执行次数、平台结果与递增版本。仅可访问当前项目任务；其他项目或不存在的 ID 返回 404。需更多验证或诊断信息时由管理员查看管理任务详情。","operationId":"get_public_job_v1_jobs__job_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"子任务的当前状态。响应示例中的 ID、时间与凭证均为占位，并非真实业务记录。","content":{"application/json":{"schema":{},"example":{"id":"job_example","batch_id":"batch_example","project_id":"prj_example","account_id":"acc_example","platform":"xiaohongshu","account_name":"品牌小红书账号","kind":"publish","content_type":"video","title":"秋日旅行记录","status":"queued","phase":"pending","schedule_mode":"immediate","run_after":"2026-10-27T02:00:00+00:00","attempts":0,"result":{},"version":1,"created_at":"2026-10-27T02:00:00+00:00","updated_at":"2026-10-27T02:00:00+00:00"}}}},"401":{"description":"缺少 Bearer 密钥，或密钥无效 / 项目已停用。"},"404":{"description":"资源不存在，或当前项目不可访问该资源。"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/healthz":{"get":{"tags":["运行状态"],"summary":"检查 API 与数据库连接","description":"无需鉴权。成功返回 status=ok，表示 API 可以响应且数据库查询成功；不检查 Worker、平台登录或发布能力。","operationId":"healthz_healthz_get","responses":{"200":{"description":"API 与数据库连接正常","content":{"application/json":{"schema":{},"example":{"status":"ok","service":"publish-center"}}}}}}}},"components":{"schemas":{"AccountCreate":{"properties":{"name":{"type":"string","maxLength":120,"minLength":1,"title":"账号名称","description":"发布中心内的显示名称，可与平台昵称不同。","examples":["品牌小红书账号"]},"platform":{"type":"string","enum":["douyin","kuaishou","xiaohongshu"],"title":"内容平台","description":"douyin=抖音，kuaishou=快手，xiaohongshu=小红书。创建后不可由账号修改接口切换。","examples":["xiaohongshu"]},"environment":{"$ref":"#/components/schemas/Environment","title":"浏览器环境","description":"此账号独立保存的语言、时区和视口配置；独立档案不代表独立公网 IP。","examples":[{"locale":"zh-CN","timezone_id":"Asia/Shanghai","viewport":{"height":900,"width":1440}}]}},"additionalProperties":false,"type":"object","required":["name","platform"],"title":"AccountCreate"},"AccountPatch":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":120,"minLength":1},{"type":"null"}],"title":"账号名称","description":"修改发布中心内显示名称，省略则不变，不可为 null。","examples":["品牌小红书账号"]},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"是否启用","description":"停用设为 disabled；重新启用设为 needs_login，需检查或恢复登录态。","examples":[true]}},"additionalProperties":false,"type":"object","title":"AccountPatch"},"AdminPublishInput":{"properties":{"idempotency_key":{"type":"string","maxLength":200,"minLength":1,"title":"业务幂等键","description":"作用域为当前项目。同键同内容返回原批次，同键不同内容返回 409。请求超时请用原键和原请求重试。","examples":["article-20261027-001"]},"targets":{"items":{"$ref":"#/components/schemas/Target"},"type":"array","maxItems":50,"minItems":1,"title":"目标账号列表","description":"1–50 个不同账号，每个目标创建独立子任务。可为目标覆盖标题、正文和标签。","examples":[[{"account_id":"acc_example"}]]},"content_type":{"type":"string","enum":["video","note"],"title":"内容类型","description":"video=单个视频；note=图文图片组。素材真实媒体类型必须匹配。","examples":["video"]},"asset_ids":{"items":{"type":"string"},"type":"array","maxItems":35,"minItems":1,"title":"素材 ID 列表","description":"使用当前项目上传后得到的 id；不能重复。video 必须恰好 1 个视频；note 为图片，抖音最多 35、快手 9、小红书 18 张。","examples":[["ast_video_example"]]},"title":{"type":"string","maxLength":100,"minLength":1,"title":"通用标题","description":"平台校验可能更严格：抖音视频 / 快手最多 30 字符；抖音图文 / 小红书最多 20 字符。可由 targets 覆盖。","examples":["秋日旅行记录"]},"body":{"type":"string","maxLength":10000,"title":"通用正文","description":"默认空字符串；抖音图文最多 1000 字符。快手将标题与非空正文用一个空行连接为作品描述。","default":"","examples":["把这一路的风景，分享给你。"]},"tags":{"items":{"type":"string"},"type":"array","maxItems":10,"title":"通用标签","description":"每个标签 1–40 字符，服务通用上限 10 个，快手最多 3 个；可由 targets 覆盖。","examples":[["旅行","生活记录"]]},"cover_asset_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"视频封面素材 ID","description":"可选，必须是当前项目的图片素材。note 图文不能另设视频封面。","examples":["ast_cover_example"]},"schedule_mode":{"type":"string","enum":["immediate","platform","server"],"title":"排期模式","description":"immediate=尽快执行；platform=提前上传并设置平台原生定时，须提前大于两小时；server=到点才开始上传，不能保证此时已公开。","default":"immediate","examples":["immediate"]},"publish_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"定时发布时间","description":"platform / server 必传且必须是未来时间，含时区；immediate 请省略。服务统一转换为 UTC。平台模式还需提前大于两小时。示例时间调用时请替换。","examples":["2026-11-01T18:00:00+08:00"]},"project_id":{"type":"string","title":"代发项目 ID","description":"使用管理员令牌代发时必须指定归属项目；素材及目标账号授权均按此项目校验。","examples":["prj_example"]}},"additionalProperties":false,"type":"object","required":["idempotency_key","targets","content_type","asset_ids","title","project_id"],"title":"AdminPublishInput","description":"管理员为指定项目代发；仍执行该项目的素材归属与账号授权校验。","examples":[{"asset_ids":["ast_video_example"],"content_type":"video","idempotency_key":"article-20261027-001","project_id":"prj_example","schedule_mode":"immediate","targets":[{"account_id":"acc_example"}],"title":"秋日旅行记录"}]},"BatchPatch":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"新标题","description":"可选，仍按目标平台上限校验；不能为 null 或空字符串。批次修改会更新全部目标的标题。","examples":["更新后的旅行记录"]},"body":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"新正文","description":"可选，空字符串可清空，不能为 null。批次修改会更新全部目标的正文。","examples":["补充这一段旅程的故事。"]},"publish_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"新的定时时间","description":"仅可修改已有 platform / server 定时任务，含时区且满足当前排期校验；不能为 null。立即任务不能通过此字段改为定时任务。","examples":["2026-11-01T18:00:00+08:00"]}},"additionalProperties":false,"type":"object","title":"BatchPatch","description":"仅提交要修改的非 null 字段；任务必须满足相应接口的可编辑条件。","examples":[{"title":"更新后的旅行记录"}]},"Body_admin_upload_api_admin_assets_post":{"properties":{"project_id":{"type":"string","title":"Project Id","description":"素材归属项目的 ID，例如 prj_example。"},"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"单个图片或视频文件；multipart 字段名必须是 file。"}},"type":"object","required":["project_id","file"],"title":"Body_admin_upload_api_admin_assets_post"},"Body_public_upload_v1_assets_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"单个图片或视频文件；multipart 字段名必须是 file。"}},"type":"object","required":["file"],"title":"Body_public_upload_v1_assets_post"},"ChallengeResponse":{"properties":{"response":{"type":"string","maxLength":2000,"minLength":1,"title":"验证响应","description":"按 challenge.kind 和 message 操作：sms 传 4–8 位数字；sms_request 传 send_sms；其他类型按提示提交。只接受有效期内、绑定任务仍执行的 pending 请求。","examples":["123456"]}},"additionalProperties":false,"type":"object","required":["response"],"title":"ChallengeResponse"},"Environment":{"properties":{"locale":{"type":"string","pattern":"^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$","title":"浏览器语言","description":"浏览器 locale，默认简体中文。","default":"zh-CN","examples":["zh-CN"]},"timezone_id":{"type":"string","const":"Asia/Shanghai","title":"浏览器时区","description":"当前版本固定为 Asia/Shanghai。","default":"Asia/Shanghai","examples":["Asia/Shanghai"]},"viewport":{"$ref":"#/components/schemas/Viewport","title":"浏览器视口","description":"独立账号浏览器环境的内容视口尺寸。","examples":[{"height":900,"width":1440}]}},"additionalProperties":false,"type":"object","title":"Environment"},"GrantsInput":{"properties":{"account_ids":{"items":{"type":"string"},"type":"array","maxItems":500,"title":"完整账号授权列表","description":"完整替换现有授权，非追加；空数组撤销全部授权。账号 ID 必须存在。","examples":[["acc_example"]]}},"additionalProperties":false,"type":"object","required":["account_ids"],"title":"GrantsInput"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ProjectCreate":{"properties":{"name":{"type":"string","maxLength":120,"minLength":1,"title":"项目名称","description":"业务网站或应用的显示名称。","examples":["品牌内容站"]},"callback_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"回调地址","description":"可选 Webhook 接收地址。默认仅允许可解析的公网 HTTP(S)，不跟随重定向。","examples":["https://example.com/webhooks/publisher"]}},"additionalProperties":false,"type":"object","required":["name"],"title":"ProjectCreate"},"ProjectPatch":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":120,"minLength":1},{"type":"null"}],"title":"项目名称","description":"仅更新请求中提供的字段；名称不可为 null。","examples":["品牌内容站"]},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"是否启用","description":"停用后项目密钥无法通过鉴权；不可为 null。","examples":[true]},"callback_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"回调地址","description":"设为 null 或空字符串可关闭回调；省略则不变。","examples":["https://example.com/webhooks/publisher"]}},"additionalProperties":false,"type":"object","title":"ProjectPatch"},"PublishInput":{"properties":{"idempotency_key":{"type":"string","maxLength":200,"minLength":1,"title":"业务幂等键","description":"作用域为当前项目。同键同内容返回原批次，同键不同内容返回 409。请求超时请用原键和原请求重试。","examples":["article-20261027-001"]},"targets":{"items":{"$ref":"#/components/schemas/Target"},"type":"array","maxItems":50,"minItems":1,"title":"目标账号列表","description":"1–50 个不同账号，每个目标创建独立子任务。可为目标覆盖标题、正文和标签。","examples":[[{"account_id":"acc_example"}]]},"content_type":{"type":"string","enum":["video","note"],"title":"内容类型","description":"video=单个视频；note=图文图片组。素材真实媒体类型必须匹配。","examples":["video"]},"asset_ids":{"items":{"type":"string"},"type":"array","maxItems":35,"minItems":1,"title":"素材 ID 列表","description":"使用当前项目上传后得到的 id；不能重复。video 必须恰好 1 个视频；note 为图片，抖音最多 35、快手 9、小红书 18 张。","examples":[["ast_video_example"]]},"title":{"type":"string","maxLength":100,"minLength":1,"title":"通用标题","description":"平台校验可能更严格：抖音视频 / 快手最多 30 字符；抖音图文 / 小红书最多 20 字符。可由 targets 覆盖。","examples":["秋日旅行记录"]},"body":{"type":"string","maxLength":10000,"title":"通用正文","description":"默认空字符串；抖音图文最多 1000 字符。快手将标题与非空正文用一个空行连接为作品描述。","default":"","examples":["把这一路的风景，分享给你。"]},"tags":{"items":{"type":"string"},"type":"array","maxItems":10,"title":"通用标签","description":"每个标签 1–40 字符，服务通用上限 10 个，快手最多 3 个；可由 targets 覆盖。","examples":[["旅行","生活记录"]]},"cover_asset_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"视频封面素材 ID","description":"可选，必须是当前项目的图片素材。note 图文不能另设视频封面。","examples":["ast_cover_example"]},"schedule_mode":{"type":"string","enum":["immediate","platform","server"],"title":"排期模式","description":"immediate=尽快执行；platform=提前上传并设置平台原生定时，须提前大于两小时；server=到点才开始上传，不能保证此时已公开。","default":"immediate","examples":["immediate"]},"publish_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"定时发布时间","description":"platform / server 必传且必须是未来时间，含时区；immediate 请省略。服务统一转换为 UTC。平台模式还需提前大于两小时。示例时间调用时请替换。","examples":["2026-11-01T18:00:00+08:00"]}},"additionalProperties":false,"type":"object","required":["idempotency_key","targets","content_type","asset_ids","title"],"title":"PublishInput","description":"一个项目的发布请求；每个目标账号会创建一个独立子任务。","examples":[{"asset_ids":["ast_video_example"],"body":"把这一路的风景，分享给你。","content_type":"video","idempotency_key":"article-20261027-001","schedule_mode":"immediate","tags":["旅行","生活记录"],"targets":[{"account_id":"acc_example"}],"title":"秋日旅行记录"}]},"ResolveInput":{"properties":{"resolution":{"type":"string","enum":["submitted","scheduled","failed"],"title":"人工核实结果","description":"submitted=确认平台已受理；scheduled=确认平台已设置预约；failed=确认平台未收到作品，之后才可安全重试。","examples":["submitted"]},"note":{"type":"string","maxLength":2000,"minLength":5,"title":"核实说明","description":"至少 5 字符，记录在平台检查到的事实，写入任务结果与审计。","examples":["已在平台作品管理页核对，作品已受理。"]}},"additionalProperties":false,"type":"object","required":["resolution","note"],"title":"ResolveInput"},"Target":{"properties":{"account_id":{"type":"string","maxLength":64,"minLength":1,"title":"目标账号 ID","description":"取自 GET /v1/accounts 的 id；当前项目必须获授权，账号必须启用。同一请求不能重复指定账号。","examples":["acc_example"]},"title":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"目标专属标题","description":"可选，覆盖通用标题；仍须满足该平台的字符上限，不能用空字符串清空。","examples":["秋日旅行记录"]},"body":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"目标专属正文","description":"可选，覆盖通用正文；空字符串可清空。快手会将非空正文与标题用空行连接。","examples":["把这一路的风景，分享给你。"]},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":10},{"type":"null"}],"title":"目标专属标签","description":"可选，覆盖通用标签；空数组清空。每个标签 1–40 字符；快手最多 3 个。","examples":[["旅行","生活记录"]]}},"additionalProperties":false,"type":"object","required":["account_id"],"title":"Target"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"Viewport":{"properties":{"width":{"type":"integer","maximum":3840.0,"minimum":800.0,"title":"浏览器视口宽度","description":"浏览器内容视口宽度，单位 px。","default":1440,"examples":[1440]},"height":{"type":"integer","maximum":2160.0,"minimum":600.0,"title":"浏览器视口高度","description":"浏览器内容视口高度，单位 px。","default":900,"examples":[900]}},"additionalProperties":false,"type":"object","title":"Viewport"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"账号","description":"获取当前项目获授权且已启用的平台账号。登录和授权由管理员完成。"},{"name":"素材","description":"上传并下载当前项目的图片 / 视频素材。发布时传入返回的素材 ID。"},{"name":"发布任务","description":"提交发布批次、查询结果、修改待执行内容，以及安全取消和重试。每个目标账号对应一个子任务。"},{"name":"管理 · 项目","description":"管理员创建接入项目、管理凭证和账号授权。"},{"name":"管理 · 账号","description":"管理员维护平台账号、浏览器环境，并发起登录或会话检查。"},{"name":"管理 · 素材","description":"管理员按项目管理和上传素材。"},{"name":"管理 · 任务","description":"管理员查看诊断信息、编辑任务和核实提交结果。"},{"name":"管理 · 人工验证","description":"查看与账号 / 任务绑定的验证请求，并在有效期内响应。"},{"name":"管理 · Webhook","description":"查看状态通知的投递记录，重试失败回调；重试回调不会重新发布作品。"},{"name":"管理 · 运维","description":"管理后台概览、配置摘要和审计记录。"},{"name":"运行状态","description":"无需鉴权的基础健康检查。"}]}