{"openapi":"3.1.0","info":{"title":"电商 AIGC 工作台 API","description":"本机异步图片、音频、视频任务。先 `POST /api/uploads` 上传素材，再将响应的 `id` 填入任务的 `inputs`。\n\n状态流转：`queued` → `running` → `succeeded` / `failed` / `cancelled`。查询 `GET /api/jobs/{id}`，成功后通过 `artifacts[].url` 下载，追加 `?download=true` 强制下载。\n\n| kind | 必要 inputs | 常用 params |\n| --- | --- | --- |\n| remove_background | image；mask / background_image 可选 | mode: auto / color / mask；key_color: #00ff00；tolerance: 60；feather: 15；background_color: null 或 #RRGGBB |\n| virtual_try_on | model_image, garment_image | garment_type: upper / lower / overall；garment_photo_type: flat-lay / model；prompt 可选；steps: 30；seed: 42。原生分辨率 576×864 |\n| image_edit | image；identity / face_swap 还需要 reference_image | mode: instruction / identity / face_swap；prompt；strength: 0.05–1；guidance_scale: 1–15；steps；seed |\n| asr | audio | language: zh / en 等或 null；beam_size: 1–10；word_timestamps: true；device: cpu / cuda |\n| tts | reference_audio 可选 | text 必填；prompt_text: 参考音频对应文字；speed: 0.5–2 |\n| lip_sync | image 或 video，加 audio | fps: 24–30；bbox_shift: -30–30 |\n| image_to_video | image | prompt 必填；duration_seconds: 1–60；width: 832；height: 480；steps: 1–50；vram_margin_gb: 4 |\n| long_video | images: 1–8 个上传 ID | prompt 必填；duration_seconds 固定 60；scene_descriptions 可选且与图片一一对应；使用 Codex SDK + MiniMax-H3 |\n\n`image_edit` 的 `identity` 模式省略参数时使用：`steps=35`、`strength=0.4`、`identity_scale=0.6`、`guidance_scale=6`，以及 `negative_prompt=\"painting, illustration, cartoon, deformed, disfigured, distorted face, blurry, low quality\"`。这些默认值仅适用于身份保持模式，不改变 `instruction` 模式；显式传入的参数优先。\n\n模型安装及具体模式状态以 `/api/capabilities` 为准。未安装模型的任务会明确失败并保留错误与日志。上传支持 PNG / JPEG / WebP / BMP、WAV / MP3 / FLAC / OGG / M4A / AAC、MP4 / WebM；默认上限 256 MiB，音视频最长 3600 秒。所有生成任务顺序执行，避免 GPU 模型同时占用显存。\n\n错误格式：`{\"detail\": {\"code\": \"invalid_request\", \"message\": \"说明\"}}`。常用状态码：400 空文件；404 不存在；413 文件过大；415 不支持媒体；422 参数或素材类型错误；429 队列已满；507 存储空间不足。\n","version":"1.0.0"},"paths":{"/api/auth/session":{"get":{"summary":"Current Session","operationId":"current_session_api_auth_session_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/auth/login":{"post":{"summary":"Password Login","operationId":"password_login_api_auth_login_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/auth/code":{"post":{"summary":"Send Code","operationId":"send_code_api_auth_code_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/auth/register":{"post":{"summary":"Register","operationId":"register_api_auth_register_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/auth/code-login":{"post":{"summary":"Code Login","operationId":"code_login_api_auth_code_login_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/auth/logout":{"post":{"summary":"Logout","operationId":"logout_api_auth_logout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/billing/quote":{"post":{"summary":"Quote","operationId":"quote_api_billing_quote_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/billing/balance":{"get":{"summary":"Balance","operationId":"balance_api_billing_balance_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/billing/ledger":{"get":{"summary":"Ledger","operationId":"ledger_api_billing_ledger_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/users":{"get":{"summary":"Users","operationId":"users_api_admin_users_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"summary":"Add User","operationId":"add_user_api_admin_users_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/admin/billing/adjust":{"post":{"summary":"Adjust","operationId":"adjust_api_admin_billing_adjust_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/admin/billing/prices":{"get":{"summary":"Prices","operationId":"prices_api_admin_billing_prices_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"put":{"summary":"Save Prices","operationId":"save_prices_api_admin_billing_prices_put","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/admin/billing/orders":{"get":{"summary":"Admin Orders","operationId":"admin_orders_api_admin_billing_orders_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/payments/options":{"get":{"summary":"Payment Options","operationId":"payment_options_api_payments_options_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/payments/orders":{"post":{"summary":"Create Order","operationId":"create_order_api_payments_orders_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"get":{"summary":"Orders","operationId":"orders_api_payments_orders_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/payments/orders/{order_id}":{"get":{"summary":"Order","operationId":"order_api_payments_orders__order_id__get","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Refresh"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/payments/notify":{"get":{"summary":"Notify","operationId":"notify_api_payments_notify_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Notify","operationId":"notify_api_payments_notify_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/health":{"get":{"tags":["系统"],"summary":"服务健康状态","description":"报告 API 和执行器锁状态；模型及 GPU 就绪情况请查询 /api/capabilities。","operationId":"health_api_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/capabilities":{"get":{"tags":["系统"],"summary":"功能、模型及安装状态","description":"包含八类功能、子模式就绪状态、模型来源/路径/许可/体积、GPU 快照与队列并发数。后台每 30 秒按需刷新，不阻塞 HTTP；首次返回 status_check.state=checking 且不声明就绪。旧快照标记 stale，超过 5 分钟未刷新则不再声明功能/GPU 可用。installed 仅表示非空目录；available 表示文件和依赖检查通过，实际生成结果以任务记录为准。","operationId":"capabilities_api_capabilities_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapabilitiesResponse"}}}}}}},"/api/uploads":{"post":{"tags":["素材"],"summary":"上传图片、音频或视频","description":"使用 multipart/form-data 的 file 字段上传。服务根据实际媒体内容检测 MIME 和类型，不信任扩展名。返回的 id 用于创建任务，url 用于预览；不会返回内部存储路径。","operationId":"upload_api_uploads_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_api_uploads_post"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadResponse"}}}},"400":{"description":"上传请求不合法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"empty_upload":{"summary":"不能上传空文件","value":{"detail":{"code":"empty_upload","message":"不能上传空文件"}}},"invalid_content_length":{"summary":"Content-Length 不合法","value":{"detail":{"code":"invalid_content_length","message":"Content-Length 不合法"}}}}}}},"413":{"description":"超过文件大小、像素或时长限制","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"upload_too_large":{"summary":"文件不得超过 256 MiB","value":{"detail":{"code":"upload_too_large","message":"文件不得超过 256 MiB"}}},"image_too_large":{"summary":"图片像素总数不得超过 4000 万","value":{"detail":{"code":"image_too_large","message":"图片像素总数不得超过 4000 万"}}},"invalid_media_duration":{"summary":"音视频时长必须在 0 到 3600 秒之间","value":{"detail":{"code":"invalid_media_duration","message":"音视频时长必须在 0 到 3600 秒之间"}}}}}}},"415":{"description":"文件内容无法识别或媒体类型不支持","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unsupported_media":{"summary":"文件不是有效的图片、音频或视频","value":{"detail":{"code":"unsupported_media","message":"文件不是有效的图片、音频或视频"}}}}}}},"422":{"description":"请求字段或上传素材类型校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_request":{"summary":"请求参数校验失败","value":{"detail":{"code":"invalid_request","message":"请求参数校验失败","fields":[{"field":"body","message":"视频生成需要 prompt 场景描述"}]}}},"invalid_input_type":{"summary":"audio 需要 audio，实际为 image","value":{"detail":{"code":"invalid_input_type","message":"audio 需要 audio，实际为 image"}}},"upload_not_found":{"summary":"上传素材不存在: 0123456789abcdef0123456789abcdef","value":{"detail":{"code":"upload_not_found","message":"上传素材不存在: 0123456789abcdef0123456789abcdef"}}}}}}},"507":{"description":"素材与任务存储空间不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"storage_full":{"summary":"素材及任务存储空间不足","value":{"detail":{"code":"storage_full","message":"素材及任务存储空间不足"}}}}}}}}}},"/api/uploads/{upload_id}":{"get":{"tags":["素材"],"summary":"读取已上传素材","description":"返回上传文件二进制内容，默认 inline 预览；不返回素材元数据 JSON。","operationId":"uploaded_file_api_uploads__upload_id__get","parameters":[{"name":"upload_id","in":"path","required":true,"schema":{"type":"string","title":"Upload Id"}}],"responses":{"200":{"description":"文件内容；Content-Type 由素材或产物类型决定。","content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"image/bmp":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}},"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/flac":{"schema":{"type":"string","format":"binary"}},"audio/ogg":{"schema":{"type":"string","format":"binary"}},"audio/mp4":{"schema":{"type":"string","format":"binary"}},"audio/aac":{"schema":{"type":"string","format":"binary"}},"video/mp4":{"schema":{"type":"string","format":"binary"}},"video/webm":{"schema":{"type":"string","format":"binary"}},"text/plain":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"string","format":"binary"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"素材、任务或产物不存在","content":{"application/json":{"examples":{"job_not_found":{"summary":"任务不存在","value":{"detail":{"code":"job_not_found","message":"任务不存在"}}},"upload_not_found":{"summary":"上传素材不存在","value":{"detail":{"code":"upload_not_found","message":"上传素材不存在"}}},"artifact_not_found":{"summary":"任务产物不存在","value":{"detail":{"code":"artifact_not_found","message":"任务产物不存在"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"请求字段或上传素材类型校验失败","content":{"application/json":{"examples":{"invalid_request":{"summary":"请求参数校验失败","value":{"detail":{"code":"invalid_request","message":"请求参数校验失败","fields":[{"field":"body","message":"视频生成需要 prompt 场景描述"}]}}},"invalid_input_type":{"summary":"audio 需要 audio，实际为 image","value":{"detail":{"code":"invalid_input_type","message":"audio 需要 audio，实际为 image"}}},"upload_not_found":{"summary":"上传素材不存在: 0123456789abcdef0123456789abcdef","value":{"detail":{"code":"upload_not_found","message":"上传素材不存在: 0123456789abcdef0123456789abcdef"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/jobs":{"post":{"tags":["任务"],"summary":"创建异步生成任务","description":"HTTP 202 表示已持久化并排队，不表示生成完成。使用返回的 id 轮询任务；模型缺失、推理失败及 GPU 故障等执行错误记录在终态 failed 的 error 字段。不会自动重试失败任务。","operationId":"create_job_api_jobs_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreate"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"422":{"description":"请求字段或上传素材类型校验失败","content":{"application/json":{"examples":{"invalid_request":{"summary":"请求参数校验失败","value":{"detail":{"code":"invalid_request","message":"请求参数校验失败","fields":[{"field":"body","message":"视频生成需要 prompt 场景描述"}]}}},"invalid_input_type":{"summary":"audio 需要 audio，实际为 image","value":{"detail":{"code":"invalid_input_type","message":"audio 需要 audio，实际为 image"}}},"upload_not_found":{"summary":"上传素材不存在: 0123456789abcdef0123456789abcdef","value":{"detail":{"code":"upload_not_found","message":"上传素材不存在: 0123456789abcdef0123456789abcdef"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"任务队列已满","content":{"application/json":{"examples":{"queue_full":{"summary":"任务队列已满，请等待现有任务完成","value":{"detail":{"code":"queue_full","message":"任务队列已满，请等待现有任务完成"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["任务"],"summary":"分页查询任务","description":"按创建时间倒序返回任务，使用 limit/offset 分页。服务重启后任务记录仍保留。","operationId":"jobs_api_jobs_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"每页最多返回的任务数","default":50,"title":"Limit"},"description":"每页最多返回的任务数"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"跳过的任务数量","default":0,"title":"Offset"},"description":"跳过的任务数量"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobListResponse"}}}},"422":{"description":"请求字段或上传素材类型校验失败","content":{"application/json":{"examples":{"invalid_request":{"summary":"请求参数校验失败","value":{"detail":{"code":"invalid_request","message":"请求参数校验失败","fields":[{"field":"body","message":"视频生成需要 prompt 场景描述"}]}}},"invalid_input_type":{"summary":"audio 需要 audio，实际为 image","value":{"detail":{"code":"invalid_input_type","message":"audio 需要 audio，实际为 image"}}},"upload_not_found":{"summary":"上传素材不存在: 0123456789abcdef0123456789abcdef","value":{"detail":{"code":"upload_not_found","message":"上传素材不存在: 0123456789abcdef0123456789abcdef"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/jobs/{job_id}":{"get":{"tags":["任务"],"summary":"查询任务状态和产物下载地址","description":"建议每 2–5 秒轮询，直到 succeeded、failed 或 cancelled。progress 是阶段百分比，不是剩余时间估算。成功产物通过 artifacts[].url 预览或下载。","operationId":"get_job_api_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"404":{"description":"素材、任务或产物不存在","content":{"application/json":{"examples":{"job_not_found":{"summary":"任务不存在","value":{"detail":{"code":"job_not_found","message":"任务不存在"}}},"upload_not_found":{"summary":"上传素材不存在","value":{"detail":{"code":"upload_not_found","message":"上传素材不存在"}}},"artifact_not_found":{"summary":"任务产物不存在","value":{"detail":{"code":"artifact_not_found","message":"任务产物不存在"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"请求字段或上传素材类型校验失败","content":{"application/json":{"examples":{"invalid_request":{"summary":"请求参数校验失败","value":{"detail":{"code":"invalid_request","message":"请求参数校验失败","fields":[{"field":"body","message":"视频生成需要 prompt 场景描述"}]}}},"invalid_input_type":{"summary":"audio 需要 audio，实际为 image","value":{"detail":{"code":"invalid_input_type","message":"audio 需要 audio，实际为 image"}}},"upload_not_found":{"summary":"上传素材不存在: 0123456789abcdef0123456789abcdef","value":{"detail":{"code":"upload_not_found","message":"上传素材不存在: 0123456789abcdef0123456789abcdef"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/jobs/{job_id}/cancel":{"post":{"tags":["任务"],"summary":"取消排队中或运行中的任务","description":"排队任务立即 cancelled；运行任务先设置 cancel_requested=true，再由执行器终止该任务的子进程组并进入 cancelled。重复取消或取消终态任务安全，不改变已有终态。","operationId":"cancel_job_api_jobs__job_id__cancel_post","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"404":{"description":"素材、任务或产物不存在","content":{"application/json":{"examples":{"job_not_found":{"summary":"任务不存在","value":{"detail":{"code":"job_not_found","message":"任务不存在"}}},"upload_not_found":{"summary":"上传素材不存在","value":{"detail":{"code":"upload_not_found","message":"上传素材不存在"}}},"artifact_not_found":{"summary":"任务产物不存在","value":{"detail":{"code":"artifact_not_found","message":"任务产物不存在"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"请求字段或上传素材类型校验失败","content":{"application/json":{"examples":{"invalid_request":{"summary":"请求参数校验失败","value":{"detail":{"code":"invalid_request","message":"请求参数校验失败","fields":[{"field":"body","message":"视频生成需要 prompt 场景描述"}]}}},"invalid_input_type":{"summary":"audio 需要 audio，实际为 image","value":{"detail":{"code":"invalid_input_type","message":"audio 需要 audio，实际为 image"}}},"upload_not_found":{"summary":"上传素材不存在: 0123456789abcdef0123456789abcdef","value":{"detail":{"code":"upload_not_found","message":"上传素材不存在: 0123456789abcdef0123456789abcdef"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/jobs/{job_id}/logs":{"get":{"tags":["任务"],"summary":"读取最近的任务日志","description":"以 JSON 的 logs 字段返回最近最多 256 KiB 文本；不是流式接口。尚无日志时为空字符串。","operationId":"job_logs_api_jobs__job_id__logs_get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobLogsResponse"}}}},"404":{"description":"素材、任务或产物不存在","content":{"application/json":{"examples":{"job_not_found":{"summary":"任务不存在","value":{"detail":{"code":"job_not_found","message":"任务不存在"}}},"upload_not_found":{"summary":"上传素材不存在","value":{"detail":{"code":"upload_not_found","message":"上传素材不存在"}}},"artifact_not_found":{"summary":"任务产物不存在","value":{"detail":{"code":"artifact_not_found","message":"任务产物不存在"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"请求字段或上传素材类型校验失败","content":{"application/json":{"examples":{"invalid_request":{"summary":"请求参数校验失败","value":{"detail":{"code":"invalid_request","message":"请求参数校验失败","fields":[{"field":"body","message":"视频生成需要 prompt 场景描述"}]}}},"invalid_input_type":{"summary":"audio 需要 audio，实际为 image","value":{"detail":{"code":"invalid_input_type","message":"audio 需要 audio，实际为 image"}}},"upload_not_found":{"summary":"上传素材不存在: 0123456789abcdef0123456789abcdef","value":{"detail":{"code":"upload_not_found","message":"上传素材不存在: 0123456789abcdef0123456789abcdef"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/jobs/{job_id}/artifacts/{name}":{"get":{"tags":["任务"],"summary":"下载任务产物","description":"name 必须与任务 artifacts 列表中的名称完全一致，可包含子目录。只提供经过验证的任务产物，不能读取任意服务器路径。","operationId":"artifact_api_jobs__job_id__artifacts__name__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}},{"name":"download","in":"query","required":false,"schema":{"type":"boolean","description":"true 使用附件下载；false 使用 inline 预览","default":false,"title":"Download"},"description":"true 使用附件下载；false 使用 inline 预览"}],"responses":{"200":{"description":"文件内容；Content-Type 由素材或产物类型决定。","content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"image/bmp":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}},"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/flac":{"schema":{"type":"string","format":"binary"}},"audio/ogg":{"schema":{"type":"string","format":"binary"}},"audio/mp4":{"schema":{"type":"string","format":"binary"}},"audio/aac":{"schema":{"type":"string","format":"binary"}},"video/mp4":{"schema":{"type":"string","format":"binary"}},"video/webm":{"schema":{"type":"string","format":"binary"}},"text/plain":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"string","format":"binary"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"素材、任务或产物不存在","content":{"application/json":{"examples":{"job_not_found":{"summary":"任务不存在","value":{"detail":{"code":"job_not_found","message":"任务不存在"}}},"upload_not_found":{"summary":"上传素材不存在","value":{"detail":{"code":"upload_not_found","message":"上传素材不存在"}}},"artifact_not_found":{"summary":"任务产物不存在","value":{"detail":{"code":"artifact_not_found","message":"任务产物不存在"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"请求字段或上传素材类型校验失败","content":{"application/json":{"examples":{"invalid_request":{"summary":"请求参数校验失败","value":{"detail":{"code":"invalid_request","message":"请求参数校验失败","fields":[{"field":"body","message":"视频生成需要 prompt 场景描述"}]}}},"invalid_input_type":{"summary":"audio 需要 audio，实际为 image","value":{"detail":{"code":"invalid_input_type","message":"audio 需要 audio，实际为 image"}}},"upload_not_found":{"summary":"上传素材不存在: 0123456789abcdef0123456789abcdef","value":{"detail":{"code":"upload_not_found","message":"上传素材不存在: 0123456789abcdef0123456789abcdef"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ArtifactResponse":{"properties":{"name":{"type":"string","title":"Name","description":"任务目录内的相对文件名","examples":["result.png","video.mp4","transcript.srt"]},"media_type":{"type":"string","title":"Media Type","description":"产物 MIME 类型","examples":["video/mp4"]},"size":{"type":"integer","minimum":1.0,"title":"Size","description":"产物字节数"},"url":{"type":"string","title":"Url","description":"同源预览或下载地址；追加 ?download=true 强制附件下载","examples":["/api/jobs/0123456789abcdef0123456789abcdef/artifacts/video.mp4"]}},"type":"object","required":["name","media_type","size","url"],"title":"ArtifactResponse"},"Body_upload_api_uploads_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"图片、音频或视频二进制文件；默认最大 256 MiB"}},"type":"object","required":["file"],"title":"Body_upload_api_uploads_post"},"CapabilitiesResponse":{"properties":{"capabilities":{"items":{"$ref":"#/components/schemas/CapabilityResponse"},"type":"array","title":"Capabilities"},"models":{"items":{"$ref":"#/components/schemas/ModelResponse"},"type":"array","title":"Models"},"gpu":{"$ref":"#/components/schemas/GPUResponse"},"data_root":{"type":"string","title":"Data Root"},"queue_concurrency":{"type":"integer","minimum":1.0,"title":"Queue Concurrency","description":"后台队列并发数；默认 1，顺序占用 GPU"},"notes":{"items":{"type":"string"},"type":"array","title":"Notes"},"status_check":{"anyOf":[{"$ref":"#/components/schemas/CapabilityCheck"},{"type":"null"}],"description":"后台检查的时效性；客户端应区分正在检查、陈旧快照与明确不可用"}},"additionalProperties":true,"type":"object","required":["capabilities","models","gpu","data_root","queue_concurrency","notes"],"title":"CapabilitiesResponse"},"CapabilityCheck":{"properties":{"state":{"type":"string","enum":["checking","current","stale","error"],"title":"State","description":"状态检查新鲜度，不是模型生成成功状态。首次 checking；30 秒后 stale；5 分钟未更新则 error 且不再声明可用。"},"refreshing":{"type":"boolean","title":"Refreshing","description":"是否已有一次后台检查在执行；不会为并发请求重复启动检查"},"checked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Checked At","description":"最近一次成功完成状态检查的 UTC 时间；首次尚未完成时为 null"},"age_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Age Seconds","description":"最近成功状态快照的年龄秒数"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"最近一次后台检查失败的原因；与生成任务 error 独立"}},"type":"object","required":["state","refreshing","checked_at","age_seconds","error"],"title":"CapabilityCheck"},"CapabilityResponse":{"properties":{"available":{"type":"boolean","title":"Available","description":"文件和依赖就绪，不代表本次生成必然成功"},"reason":{"type":"string","title":"Reason","description":"就绪说明或缺失依赖"},"kind":{"type":"string","enum":["remove_background","virtual_try_on","image_edit","asr","tts","lip_sync","image_to_video","long_video"],"title":"Kind"},"title":{"type":"string","title":"Title"},"category":{"type":"string","enum":["image","audio","video"],"title":"Category"},"description":{"type":"string","title":"Description"},"model":{"type":"string","title":"Model","description":"实际使用的模型或处理方式"},"modes":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/ModeStatus"},"type":"object"},{"type":"null"}],"title":"Modes","description":"各子模式的独立就绪状态；应按选定模式判断"},"license_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License Note","description":"该功能的模型许可注意事项"}},"additionalProperties":true,"type":"object","required":["available","reason","kind","title","category","description","model"],"title":"CapabilityResponse"},"ErrorDetail":{"properties":{"code":{"type":"string","title":"Code","description":"可供程序处理的错误标识","examples":["generation_failed","worker_interrupted","gpu_unavailable"]},"message":{"type":"string","title":"Message","description":"可读失败原因；完整执行记录见任务日志"},"fields":{"anyOf":[{"items":{"$ref":"#/components/schemas/ValidationField"},"type":"array"},{"type":"null"}],"title":"Fields","description":"422 请求校验错误可附带逐字段说明"}},"type":"object","required":["code","message"],"title":"ErrorDetail"},"ErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/ErrorDetail"}},"type":"object","required":["detail"],"title":"ErrorResponse"},"GPUResponse":{"properties":{"available":{"type":"boolean","title":"Available","description":"最近一次 nvidia-smi 是否成功；快照缓存约 10 秒"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"memory_total_mb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Memory Total Mb","description":"显卡总显存 MiB"},"memory_used_mb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Memory Used Mb","description":"显卡已用显存 MiB"},"utilization":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Utilization","description":"GPU 利用率百分比"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"GPU 不可用时的错误说明"}},"additionalProperties":true,"type":"object","required":["available"],"title":"GPUResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","const":"ok","title":"Status","description":"API 可响应，不等同于模型或 GPU 可用"},"worker_enabled":{"type":"boolean","title":"Worker Enabled","description":"API 是否配置为自动启动后台执行器"},"worker_running":{"type":"boolean","title":"Worker Running","description":"当前数据目录的执行器锁是否被持有"},"data_root":{"type":"string","title":"Data Root","description":"服务数据根目录","examples":["/data_12T/aigc-web"]}},"type":"object","required":["status","worker_enabled","worker_running","data_root"],"title":"HealthResponse"},"JobCreate":{"properties":{"kind":{"type":"string","enum":["remove_background","virtual_try_on","image_edit","asr","tts","lip_sync","image_to_video","long_video"],"title":"Kind","description":"功能名称；可用模型和安装状态通过 /api/capabilities 查询"},"inputs":{"additionalProperties":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}]},"type":"object","title":"Inputs","description":"/api/uploads 返回的上传 ID。图片任务 image；试衣 model_image + garment_image；ASR audio；口型 image 或 video + audio；长视频 images 数组必须包含 1–8 个图片上传 ID。"},"params":{"additionalProperties":true,"type":"object","title":"Params","description":"生成参数。TTS 必填 text；视频使用 prompt、duration_seconds、seed；抠图 mode=auto 或 color，key_color 为背景色；模型的详细参数见页面接口说明。"},"expected_price_revision":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Expected Price Revision","description":"报价版本，创建任务前由 /api/billing/quote 获取"}},"additionalProperties":false,"type":"object","required":["kind"],"title":"JobCreate","examples":[{"inputs":{"image":"0123456789abcdef0123456789abcdef"},"kind":"remove_background","params":{"feather":15,"key_color":"#00ff00","mode":"color","tolerance":60}},{"inputs":{"garment_image":"fedcba9876543210fedcba9876543210","model_image":"0123456789abcdef0123456789abcdef"},"kind":"virtual_try_on","params":{"garment_type":"upper","seed":42,"steps":30}},{"inputs":{"image":"0123456789abcdef0123456789abcdef"},"kind":"image_edit","params":{"mode":"instruction","prompt":"将商品背景改为柔和的米白色，保留商品外观。","steps":30}},{"inputs":{"audio":"0123456789abcdef0123456789abcdef"},"kind":"asr","params":{"beam_size":5,"device":"cpu","language":"zh","word_timestamps":true}},{"inputs":{},"kind":"tts","params":{"speed":1,"text":"欢迎来到我们的新品展示。"}},{"inputs":{"audio":"fedcba9876543210fedcba9876543210","image":"0123456789abcdef0123456789abcdef"},"kind":"lip_sync","params":{"bbox_shift":0,"fps":25}},{"inputs":{"image":"0123456789abcdef0123456789abcdef"},"kind":"image_to_video","params":{"duration_seconds":10,"height":480,"prompt":"镜头缓缓推进，展示商品的材质和细节。","width":832}},{"inputs":{"images":["0123456789abcdef0123456789abcdef"]},"kind":"long_video","params":{"duration_seconds":60,"prompt":"展示商品材质、细节和使用场景，保持商品外观一致。"}}]},"JobError":{"properties":{"code":{"type":"string","title":"Code","description":"可供程序处理的错误标识","examples":["generation_failed","worker_interrupted","gpu_unavailable"]},"message":{"type":"string","title":"Message","description":"可读失败原因；完整执行记录见任务日志"}},"type":"object","required":["code","message"],"title":"JobError"},"JobListResponse":{"properties":{"jobs":{"items":{"$ref":"#/components/schemas/JobResponse"},"type":"array","title":"Jobs","description":"按创建时间倒序的任务页；少于 limit 表示当前已到末页"}},"type":"object","required":["jobs"],"title":"JobListResponse"},"JobLogsResponse":{"properties":{"logs":{"type":"string","title":"Logs","description":"最近最多 256 KiB 的 UTF-8 日志；尚未执行时可能为空","examples":["[8.0%] 正在加载本地模型\n[95.0%] 模型推理完成，正在验证输出\n"]}},"type":"object","required":["logs"],"title":"JobLogsResponse"},"JobResponse":{"properties":{"id":{"type":"string","pattern":"^[a-f0-9]{32}$","title":"Id","description":"持久化任务 ID"},"kind":{"type":"string","enum":["remove_background","virtual_try_on","image_edit","asr","tts","lip_sync","image_to_video","long_video"],"title":"Kind"},"inputs":{"additionalProperties":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}]},"type":"object","title":"Inputs","description":"原始上传 ID 映射，不暴露服务器文件路径"},"params":{"additionalProperties":true,"type":"object","title":"Params","description":"已保存的生成参数"},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"],"title":"Status","description":"queued 排队；running 执行；其余为终态。服务重启发现中断任务时标记 failed，不自动重试。"},"progress":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Progress","description":"阶段进度百分比，不代表预计完成时间；成功为 100"},"message":{"type":"string","title":"Message","description":"最新执行阶段或终态说明"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"UTC 创建时间"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"UTC 最近状态更新时间"},"artifacts":{"items":{"$ref":"#/components/schemas/ArtifactResponse"},"type":"array","title":"Artifacts","description":"已验证的产物列表；成功前通常为空"},"error":{"anyOf":[{"$ref":"#/components/schemas/JobError"},{"type":"null"}],"description":"执行失败原因；未失败为 null。异步失败通过此字段返回，不改变查询接口的 HTTP 200。"},"cancel_requested":{"type":"boolean","title":"Cancel Requested","description":"是否已请求取消；运行任务须等待子进程结束后进入 cancelled"},"billing":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Billing"}},"type":"object","required":["id","kind","inputs","params","status","progress","message","created_at","updated_at","artifacts","error","cancel_requested"],"title":"JobResponse"},"ModeStatus":{"properties":{"available":{"type":"boolean","title":"Available","description":"文件和依赖就绪，不代表本次生成必然成功"},"reason":{"type":"string","title":"Reason","description":"就绪说明或缺失依赖"}},"additionalProperties":true,"type":"object","required":["available","reason"],"title":"ModeStatus"},"ModelResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"directory":{"type":"string","title":"Directory","description":"相对于模型根目录的安装子目录"},"source":{"type":"string","title":"Source","description":"上游模型或项目来源"},"size_note":{"type":"string","title":"Size Note","description":"权重体积说明，不等同于显存用量"},"runtime_note":{"type":"string","title":"Runtime Note","description":"设备、运行环境及卸载策略说明"},"license":{"type":"string","title":"License","description":"上游许可摘要；商业使用前应阅读完整模型许可"},"installed":{"type":"boolean","title":"Installed","description":"目录存在且非空；首次检查中为 false，但不表示已确认缺失。完整运行就绪以 capabilities 为准。"},"installation_state":{"anyOf":[{"type":"string","const":"checking"},{"type":"null"}],"title":"Installation State","description":"首次后台检查尚未完成时返回 checking；正式快照不包含此字段"},"path":{"type":"string","title":"Path","description":"本机模型目录"},"downloaded_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Downloaded Bytes","description":"下载清单记录的总字节数，无清单时为 null"},"source_used":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Used","description":"实际下载来源，无清单时为 null"}},"additionalProperties":true,"type":"object","required":["id","name","directory","source","size_note","runtime_note","license","installed","path","downloaded_bytes","source_used"],"title":"ModelResponse"},"UploadResponse":{"properties":{"id":{"type":"string","pattern":"^[a-f0-9]{32}$","title":"Id","description":"后续 inputs 使用的上传 ID"},"name":{"type":"string","title":"Name","description":"经过路径清理的原始文件名"},"kind":{"type":"string","enum":["image","audio","video"],"title":"Kind","description":"根据真实文件内容识别的素材类型"},"media_type":{"type":"string","title":"Media Type","description":"检测得到的 MIME 类型","examples":["image/png"]},"size":{"type":"integer","minimum":1.0,"title":"Size","description":"文件字节数"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"UTC 上传时间"},"url":{"type":"string","title":"Url","description":"同源素材预览地址","examples":["/api/uploads/0123456789abcdef0123456789abcdef"]}},"type":"object","required":["id","name","kind","media_type","size","created_at","url"],"title":"UploadResponse"},"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"},"ValidationField":{"properties":{"field":{"type":"string","title":"Field","description":"校验失败的字段路径","examples":["body.params"]},"message":{"type":"string","title":"Message","description":"该字段的校验错误说明"}},"type":"object","required":["field","message"],"title":"ValidationField"}}}}