uncloth.app 指南
由 uncloth.app API 生成的结果

成人照片滤镜
为您的应用而生

一个接口，十一种预设。上传照片，取回成品结果——无论你的平台跑在多大的量级上。

申请接入 查看 API

为生产环境而建

uncloth.app 是一套图像变换 API，面向那些需要把生成图像当作产品可靠组成部分、而非试验品的平台。你提交一张照片和所需的预设，我们返回成品结果。

接口背后的一切由我们负责运维——容量、排队、投递与恢复。你的集成只是一次带鉴权的 HTTP 调用；若需要实时进度，再加一条 WebSocket 连接。

请求的表现与我们的繁忙程度无关。同一次调用，在你接入的第一天和在峰值负载下的行为完全一致。

一张照片，全部预设

下面每个结果都来自同一张源照片，请求中除预设 id 外没有任何改动。

十一种预设

在任务中传入 feature=<id>。若省略，请求会回退到 undress。未知 id 会被拒绝并返回有效列表，因此拼写错误会明确报错，而不是返回错误的图像。

01
比基尼feature=bikini
02
胸部尺寸feature=breast_size
03
兔女郎装feature=bunny_suit
04
蕾丝内衣feature=lace_lingerie
05
绳缚feature=shibari
06
长袜feature=stocking
07
纹身feature=tattoo
08
脱衣默认feature=undress
09
啦啦队服feature=cheerleader_outfit
10
足球服feature=footy
11
袒胸feature=flash_tits

四次调用，从头到尾

01

提交照片

一次 multipart POST，带上图像、预设和同意确认。你会立即收到一个任务 id。

02

跟踪进度

轮询任务接口，或订阅 WebSocket，在处理过程中接收实时进度事件。

03

取回结果

已完成的任务带有一个产物 id。用同一把密钥获取它，即可拿到图像字节。

04

免费重试

用相同的 Idempotency-Key 重复调用，会返回原来的任务。重试绝不会产生第二个结果。

全部集成内容

一个请求头即可完成所有调用的鉴权。每个响应都限定在持有该密钥的客户范围内——任务、事件和结果都包含在内。

POST/api/v1/jobs创建任务。Multipart：image、feature、consent。带 Idempotency-Key 请求头。
GET/api/v1/jobs/:id任务状态、进度和结果 id。
GET/api/v1/artifacts/:id下载生成的图像。
GET/api/v1/features列出预设。公开接口，无需密钥。
WS/api/v1/ws发送鉴权消息后接收实时 job.updated 事件。

你的基础 URL 随密钥一同签发。

创建任务
curl -X POST https://api.uncloth.app/api/v1/jobs \
  -H "X-API-Key: $UNCLOTH_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F feature=bikini \
  -F consent=confirmed \
  -F image=@photo.jpg

# { "data": { "id": "job_...", "status": "queued" } }
取回结果
curl -H "X-API-Key: $UNCLOTH_KEY" \
  https://api.uncloth.app/api/v1/jobs/JOB_ID

# { "data": { "status": "succeeded",
#     "outputs": [ { "id": "art_..." } ] } }

curl -H "X-API-Key: $UNCLOTH_KEY" \
  https://api.uncloth.app/api/v1/artifacts/ART_ID \
  -o result.png

为持续响应而设计

容量、队列和投递链路由我们运行，你的平台无需操心。以下是关于本服务如何构建和运维的承诺。

10 分钟内删除

在您收到结果 10 分钟后，您的图片将从我们的系统中删除。不会为训练、审核或任何其他用途保留任何内容。

99.9% 可用性目标

我们据以设计、运维和度量的服务水平，在 API 边缘统计，而非以某个单一组件为准。

全球基础设施

请求由分布式容量承接，因此某一地区的需求不会变成所有人共同的队列。

自动扩缩

容量随负载变化。流量高峰只改变吞吐量，绝不改变 API 的形态或你的代码调用它的方式。

默认故障转移

任何单个组件都可被下线或替换，而不会造成需要你处理的中断。进行中的工作会被恢复，而不是丢失。

按密钥隔离

一把密钥只能看到自己的任务、事件和结果。响应绝不暴露内部标识符或基础设施细节。

以契约保证幂等

Idempotency-Key 请求头让重试变得安全。重复调用会返回原来的任务，而不是把工作做两遍。

持久化排队

已接收的工作在开始前即被记录，事后可恢复。链路中任何位置的重启都不会丢掉你的任务。

严格的输入校验

支持 JPEG、PNG 和 WebP，最大 20 MiB，按文件内容校验，而不只看文件名或声明的类型。

常见问题

如何进行鉴权？

REST 调用使用 X-API-Key 请求头。在 WebSocket 上，密钥随连接后的第一条消息发送，因此绝不会出现在 URL 或代理日志中。

请求超时会怎样？

用相同的 Idempotency-Key 重复调用。你会拿回原来的任务，不会产生第二个结果。

接受哪些格式和大小？

JPEG、PNG 和 WebP，最大 20 MiB。系统会校验文件的实际内容，因此改名或类型标注错误的文件会被拒绝。

能对一张照片使用多个预设吗？

可以。每个预设都是独立的任务，因此用同一张源图为每个预设各提交一个任务，并分别跟踪。

必须轮询吗？

不必。连接 WebSocket 并完成鉴权后，你会先收到近期任务的快照，随后是实时更新。轮询仍作为备选方式保留。

是否强制要求同意？

是。缺少 consent=confirmed 的创建调用会在 API 边界被拒绝。它是必填字段，也是一项由你负责的声明。

费用如何？

价格取决于用量，在开通接入时报价。请告诉我们你的平台情况和预期吞吐量，我们会给出具体数字。

你们会保存我的图像吗？

源图像和结果保存在私有存储中，仅提供给创建它们的那把密钥。保留期限在开通接入时一并约定。

告诉我们你在做什么

接入按集成逐个授予。请描述你的平台、预期用量，以及你如何从图像中的人物处获取同意，我们会回复凭据和基础 URL。

不提供公开注册，也不提供自助密钥。