客户端接入文档

接入流程

以下路径都相对于 v1 服务根地址。当前本机地址为 http://127.0.0.1:8017；其他设备须换成这台机器可访问的 IP 和端口。请求和响应使用 HTTP；创建任务采用 multipart/form-data，其他 JSON 接口返回 application/json。

光效表

{
  "lora_exists": true,
  "lora": {"lid": "...", "rid": "...", "ckpt": "..."},
  "presets": [
    {"key": "afternoon_front", "name": "午后顺光", "prompt": "...", "tier": "...", "via": "...", "note": "..."},
    {"key": "custom", "name": "自定义", "prompt": null}
  ]
}

上方是字段示意，完整列表以接口实时返回为准。prompt=null 的预设需要同时传 light_prompt；lora_exists=false 时不能创建 Qwen 光效任务。

创建任务

上传文件经过 EXIF 方向修正并转为 RGB PNG。输出像素尺寸与修正后的 B 相同。客户端用 FormData 发送文件；不要手动指定 multipart 的 Content-Type 边界。

任务状态

{
  "job_id": "a1b2c3d4e5f6",
  "status": "queued",
  "source": "qwen",
  "batch": 8,
  "amp": "bf16",
  "light_strength": 1.0,
  "detail_strength": 0.2,
  "face_safe": true,
  "contour_safe": true,
  "light_preset": "afternoon_front",
  "light_name": "午后顺光",
  "reference_ready": false,
  "output_ready": false,
  "pipeline_required": true,
  "direct_ready": false,
  "final_ready": false,
  "final_status": "queued",
  "final_error": null,
  "final_elapsed_s": null,
  "final_metrics": null,
  "reference_size": null,
  "content_size": [6000, 4000],
  "output_size": null,
  "light_steps": 12,
  "generated_seed": null,
  "relight_elapsed_s": null,
  "fusion_elapsed_s": null,
  "elapsed_s": null,
  "model_cached": null,
  "content_features_cached": null,
  "failed_stage": null,
  "runtime_target_s": 10.0,
  "runtime_domain": "24.00MP / 单张 RTX 5090 / 工作线程开始至结果1/2和图5全部落盘；含 Qwen/SAM，不含上传、归一化与排队",
  "error": null
}

• pipeline_required=true 表示新任务必须生成三个结果。reference_ready=true 后可先下载 A；output_ready/direct_ready 分别表示结果1/2文件已准备好，output_size 在此时给出。SAM 失败时整单返回 status=failed, failed_stage=composite，结果1/2仍可下载诊断。
• 图5状态为 queued → running → completed/failed，旧任务是 not_started。新任务自动执行；只有旧任务补做或失败重试才调用 POST /api/jobs/{job_id}/final，HTTP 202；重复请求在排队、运行或完成时不会重复生成。final_error 单独报告 SAM/合成失败。
• status=failed 时读取 failed_stage 和 error。任务执行失败通过 HTTP 200 的状态对象报告。
• elapsed_s 是工作线程开始后的总耗时（包括图5），不包含上传、图像归一化与排队；relight_elapsed_s 是 Qwen 回报的推理时间；fusion_elapsed_s 到内存结果1/2完成为止；含需要时的冷启动加载，不包括 SAM 图5；final_elapsed_s 是 SAM 抠图、原尺寸合成和图5文件保存耗时。
• content_features_cached=true 表示同一原片的 v1 编码已自动复用；首次原片为 false。编码以原精度保存在 CPU，仅保留一张原片且最多 1GiB；像素、tile 布局、batch 或精度改变都会失效。每张新原片的首次耗时和复用耗时应分别统计。
• runtime_target_s 是完整后台流程的工程目标值，不是请求超时或性能保证；其统计范围见 runtime_domain。

图片与检测

图5的 final_metrics 包含 background_changed_pixels 和 person_core_changed_pixels，两项均按 measured / target / domain 返回，目标都是 0。前者对比遮罩外图5与结果2，后者对比 alpha=255 内图5与结果1。它们验证像素来源，不能验证 SAM 是否完整分出发丝、衣袖或头饰。

质量报告给出 face_count_b、matched_face_count、landmark_shift、face_overexposure_ratio、risk_level、thresholds 和 domain。位移是对齐代理图中五点平均位移除以 B 脸框最大边；过曝是 B 脸框内 A 灰度 >0.95 的比例。提示线为未标定的初始值，仅用于人工复查；face_id_score、silhouette_shift 为 null，原因见 unavailable。其他三个检测接口也返回 domain；null 不等于 0。

错误处理

业务错误通常为 {"detail":"错误说明"}；FastAPI 字段校验失败时 detail 是数组。网络中断且创建请求是否成功不明时，不要自动重复上传，以免重复生成任务。

浏览器客户端示例

以下 JavaScript 可放在与 API 同源的网页里。调用 run(contentFile) 时传入用户文件选择器拿到的 File；预设 key 从 /api/lights 读取。

const api = location.origin;

async function checkedJson(response) {
  const data = await response.json();
  if (!response.ok) throw new Error(
    typeof data.detail === 'string' ? data.detail : JSON.stringify(data.detail)
  );
  return data;
}

async function createAndWait(contentFile, presetKey) {
  const form = new FormData();
  form.append('content', contentFile);
  form.append('light_preset', presetKey);
  // 现成 A 模式：删去 light_preset，改用 form.append('reference', aFile)
  const created = await checkedJson(await fetch(`${api}/api/jobs`, {
    method: 'POST', body: form
  }));
  const id = created.job_id;
  for (;;) {
    const job = await checkedJson(await fetch(`${api}/api/jobs/${id}`));
    if (job.reference_ready) {
      // 可先显示 `${api}/api/jobs/${id}/preview/reference`
    }
    if (job.status === 'failed') throw new Error(job.error || '任务失败');
    if (job.status === 'completed' && job.final_ready) return {
      job,
      referenceUrl: `${api}/api/jobs/${id}/image/reference`,
      outputUrl: `${api}/api/jobs/${id}/output`,
      directUrl: job.direct_ready ? `${api}/api/jobs/${id}/direct` : null,
      finalUrl: `${api}/api/jobs/${id}/final`,
      finalError: job.final_error
    };
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
}

async function run(contentFile) {
  const lights = await checkedJson(await fetch(`${api}/api/lights`));
  const presetKey = lights.presets[0].key;
  return createAndWait(contentFile, presetKey);
}
// const result = await run(fileInput.files[0]);
// result.finalUrl 是最终图5；result.outputUrl/directUrl 是对照结果1/2。

若预设 prompt=null，需额外 form.append('light_prompt', 用户输入)。页面按钮里调用 run(fileInput.files[0]) 即可。

curl 示例

BASE=http://127.0.0.1:8017
curl -sS "$BASE/api/lights"

# 用预设生成 A，再交给 v1 融合。把路径换成自己的原片。
curl -sS -X POST "$BASE/api/jobs" \
  -F 'content=@/path/to/B.jpg' \
  -F 'light_preset=afternoon_front' \
  -F 'light_steps=12' -F 'batch=8' -F 'amp=bf16'

# 从上一步的 JSON 复制 job_id，持续查询直至 completed。
JOB_ID=a1b2c3d4e5f6
curl -sS "$BASE/api/jobs/$JOB_ID"
curl -sS "$BASE/api/jobs/$JOB_ID/image/reference" -o A.png
curl -sS "$BASE/api/jobs/$JOB_ID/output" -o result.png
curl -sS "$BASE/api/jobs/$JOB_ID/direct" -o result2-direct.png
curl -sS "$BASE/api/jobs/$JOB_ID/final" -o final.png

# 若已有 A，创建时改用 reference，不传 light_preset。
curl -sS -X POST "$BASE/api/jobs" \
  -F 'content=@/path/to/B.jpg' \
  -F 'reference=@/path/to/A.png'

部署注意

固定依赖：本机 Qwen LoRA 服务和 SAM 3.1 TensorRT 服务均常驻；doc/start_web.sh 先加载/预热 Qwen（含 2MP），再启动 SAM 和 v1；避免首次量化的显存峰值重叠。v1 的模型和 CUDA 缓存持续保留。

• 服务当前无登录鉴权；仅在可信网络提供访问。127.0.0.1 只能从服务本机访问。跨机器使用时由部署方设置可访问地址和网络入口。
• 当前未配置跨域 CORS。浏览器网页请与 API 同源部署，或由自己的后端转发；原生桌面/移动客户端可直接请求 HTTP API。
• 已完成的任务图片和状态保存在服务数据目录，可在服务重启后读取；排队和处理中任务不会恢复。当前没有取消任务或按客户端枚举任务的接口，请保存 job_id。
• 机器可读契约见 /openapi.json；可在 /docs 交互测试。文档列出的图片接口返回二进制图片，不是 JSON。