真实 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、purpose、channel、territory、training及idempotencyKey；只允许该许可所属Application的Key。成功受理扣一次许可额度，同参数同幂等键重试不重复扣。返回使用记录，不代表图片或视频已生成；可在沙箱许可查看剩余额度及使用记录。

实际内容回传

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

机器可读接口契约

下载 OpenAPI 接口契约（OpenAPI 3.0.3）

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

尚未接入

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