真实 API 接入与 JavaScript 客户端

此页对应当前可执行后端，不推荐未发布包、不使用占位API域名。当前资产为沙箱资料；查询不授予生成、训练或商用License。

1. 注册并验证邮箱，进入应用与API Key管理创建应用与密钥。
2. 下载下面两个文件放在同一目录，Node.js 22及以上运行；无需安装额外npm包。
3. 将Key作为私有环境变量FACEPIC_API_KEY提供给调用进程，可选FACEPIC_BASE_URL指定服务地址；运行node quickstart.mjs。
4. 在真实调用日志用返回的requestId追踪请求。

下载 JavaScript 客户端 下载可运行示例

import { FacePickClient } from './facepick-client.mjs';

const client = new FacePickClient({
  baseUrl: process.env.FACEPIC_BASE_URL ?? 'http://127.0.0.1:3110',
  apiKey: process.env.FACEPIC_API_KEY,
});
const result = await client.searchFaces('');
console.log(result.data, result.requestId);

已实现的 API Key 接口

持续分页搜索

客户端searchFacesPage(options)调用GET /api/developer/faces/page，返回data.items和data.nextCursor。首次不传cursor；后续保持query不变，传上次nextCursor，直到null。每页默认20、最多100，都会鉴权并记录调用；旧searchFaces仍返回最多100条数组。分页不保证跨页冻结快照，不授予授权。

响应与错误

成功返回{data, requestId}；失败返回{code, message, requestId, details?}。客户端抛FacePickError并保留status/code/requestId，不附带完整服务响应。撤销Key后新请求401；查询失败也可在该Key日志中追踪。

安全边界

客户端只用于服务端脚本。不要把Key放到浏览器公开源码、URL、Git或日志。非本地地址必须HTTPS；拒绝重定向，避免凭据被发送到意外目标。不自动重试，不伪造成功。完整密钥仅创建时显示一次。

已付许可使用

竞拍沙箱付款已可签发License。客户端useLicense(input)调用POST /api/developer/license-uses，输入licenseId、scene（必填，v1 禁止 adult/political）、purpose、channel、territory、training及idempotencyKey；只允许该许可所属Application的Key。成功受理扣一次许可额度，同参数同幂等键重试不重复扣。返回使用记录，不代表图片或视频已生成；可在沙箱许可查看剩余额度及使用记录。

AI 生成（模拟出图）

POST /api/developer/generations 输入与许可使用相同的licenseId、scene、purpose、channel、territory、training、idempotencyKey，可选prompt；客户端不得自带aiGenerated等AI标识（返回422）。服务端先扣一次许可次数并写入账本，再生成图片并保存到私有存储，返回记录带usageLedgerId和AI标识。生成失败不退还次数：失败也会留下FAILED记录并返回502；用同一个idempotencyKey重试只会返回这条FAILED记录，不会重新生成；要重新生成必须换新的idempotencyKey，并会再扣一次次数。

查询与下载（同一Application的API Key）：GET /api/developer/generations（limit/cursor，可选licenseId、status）分页列出本应用记录；GET /api/developer/generations/{id} 读单条（FAILED含errorCode/errorMessage）；GET /api/developer/generations/{id}/content 下载私有原图字节（Content-Disposition: attachment，X-Content-SHA256，Cache-Control: private, no-store）。FAILED记录下载返回409 GENERATION_NOT_AVAILABLE；文件缺失返回410 CONTENT_GONE。本地存储直接返回200字节；切换到COS后该接口可能302到短时签名链接（有效期≤3600秒）。图片从不公开URL暴露。

实际内容回传

submitContent(input)调用POST /api/developer/contents；输入useId、title、mimeType、dataBase64和idempotencyKey。支持PNG/JPEG/MP4实际文件，最大5MiB；同Use只一份内容，回传不再扣次数。文件保存本地沙箱并进入独立人工审核，自动审核NOT_CONFIGURED。可在内容记录查看文件哈希和审批状态；仅鉴权下载，不公开发布。

机器可读接口契约

下载 OpenAPI 接口契约（OpenAPI 3.0.3）

覆盖当前应用Key接口及健康检查；不含Cookie控制台、管理员接口或Webhook投递结构，不含未实现的模型生成。只在受控本地工具导入，密钥不要交给公共在线文档站点。参数符合结构不代表已获得许可，后端仍检查身份、范围、状态与额度。

尚未接入

真实支付/生成/自动审核提供方和支付仍待后续集成；按次应计分账已实现，不代表付款。这里不是公开npm发布包，当前交付为仓库可执行客户端文件。