cURL · 幽灵模特 API
幽灵模特 API 使用 cURL
一句话总结
导出 PHOTTA_API_KEY,携带文档指定的 JSON body 向 https://api.photta.app/api/v1/api/v1/ghost-mannequin 发送 POST 请求,获取生成任务 ID,然后每隔 3 秒对 /api/v1/ghost-mannequin/{id} 发起 GET 轮询,直到 data.status 为 completed。搭配 jq 提取输出 URL。
- 常规耗时: 1.5–4 min
- Credits: 2K 分辨率 4 credits · 4K 分辨率 5 credits
- 处理方式: 异步,轮询
- 限制: 600 次请求/分钟
- 身份验证: Bearer key
本页所有数据均来自 Photta API 文档 · 已验证
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
"back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
"image_side": "front",
"angle": "side",
"style": "3d",
"background_color": "white",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "closed front, cream interior lining",
"brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
# $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed".
for i in $(seq 1 120); do
RESULT=$(curl -s "https://api.photta.app/api/v1/ghost-mannequin/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY")
STATUS=$(echo "$RESULT" | jq -r '.data.status')
[ "$STATUS" = "completed" ] && break
[ "$STATUS" = "failed" ] && echo "generation failed" && exit 1
sleep 3
done
echo "$RESULT" | jq -r '.data.output_url'const res = await fetch("https://api.photta.app/api/v1/ghost-mannequin", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
"back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
"image_side": "front",
"angle": "side",
"style": "3d",
"background_color": "white",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "closed front, cream interior lining",
"brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}),
});
const { data } = await res.json(); // data.id, data.status
async function waitFor(id) {
for (let attempt = 0; attempt < 120; attempt++) {
const res = await fetch(`https://api.photta.app/api/v1/ghost-mannequin/${id}`, { headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}` } });
const { data } = await res.json();
if (data.status === "completed") return data.output_url;
if (data.status === "failed") throw new Error(data.error_message ?? "generation failed");
await new Promise((r) => setTimeout(r, 3000));
}
throw new Error("timed out after 6 minutes");
}import os, requests
res = requests.post(
"https://api.photta.app/api/v1/ghost-mannequin",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
"back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
"image_side": "front",
"angle": "side",
"style": "3d",
"background_color": "white",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "closed front, cream interior lining",
"brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
},
)
data = res.json()["data"] # data["id"], data["status"]
import time
def wait_for(job_id):
for _ in range(120):
res = requests.get(f"https://api.photta.app/api/v1/ghost-mannequin/{job_id}", headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"})
data = res.json()["data"]
if data["status"] == "completed":
return data["output_url"]
if data["status"] == "failed":
raise RuntimeError(data.get("error_message", "generation failed"))
time.sleep(3)
raise TimeoutError("timed out after 6 minutes")概览
概览
- 端点
- POST /api/v1/ghost-mannequin
- 身份验证
- Bearer API 密钥
- 处理方式
- 异步 — 轮询状态端点
- 常规耗时
- 1.5–4 min
- Credits
- 2K 分辨率 4 credits · 4K 分辨率 5 credits
- 宽高比
- 3:4 · 1:1 · 4:3 · 9:16 · 16:9
- 输入限制
- 单张图片最大 10 MB;支持 JPEG, PNG, WebP
- 幂等性
- 否
工作原理
五个终端步骤,除 curl 和 jq 外零额外依赖。
步骤 1
注册并生成密钥
前往 ai.photta.app,打开 Developers 标签页,点击 Generate API key。正式环境密钥以 `photta_live_` 开头。
步骤 2
导出密钥环境变量
在终端配置文件或 `.envrc` 文件中加入 `export PHOTTA_API_KEY="photta_live_xxx"`,后续所有 curl 调用都将自动读取该变量。
curl --version # macOS, Linux, WSL and Windows 10+ ship it export PHOTTA_API_KEY="photta_live_xxxxx"步骤 3
固定 base URL
设置 `export PHOTTA_BASE_URL="https://api.photta.app/api/v1"`,让 curl 命令更精简。
export PHOTTA_BASE_URL="https://api.photta.app/api/v1" export AUTH_HEADER="Authorization: Bearer $PHOTTA_API_KEY"步骤 4
提交并轮询
向 `$PHOTTA_BASE_URL/api/v1/ghost-mannequin` 发送 POST 请求获取 ID,然后每 3 秒循环执行一次 `curl $PHOTTA_BASE_URL/api/v1/ghost-mannequin/{id}`。将响应通过管道传给 jq,以便干净利落地提取 `.data.status`。
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \ -H "Authorization: Bearer $PHOTTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg", "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg", "image_side": "front", "angle": "side", "style": "3d", "background_color": "white", "resolution": "2K", "aspect_ratio": "3:4", "user_instruction": "closed front, cream interior lining", "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67" }') ID=$(echo "$RESPONSE" | jq -r '.data.id') # $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed". for i in $(seq 1 120); do RESULT=$(curl -s "https://api.photta.app/api/v1/ghost-mannequin/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY") STATUS=$(echo "$RESULT" | jq -r '.data.status') [ "$STATUS" = "completed" ] && break [ "$STATUS" = "failed" ] && echo "generation failed" && exit 1 sleep 3 done echo "$RESULT" | jq -r '.data.output_url'步骤 5
持久化存储结果
任务完成后,使用 jq 提取出 `.data.output_url`,并通过 `curl -o` 将字节流写入本地存储——随时可用于下一个流水线步骤。
错误
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_error - An internal server error occurred. Retry later.
case "$STATUS_CODE" in
402) echo "insufficient_credits_error — top up before retrying" ;;
429) echo "rate_limit_error — wait the Retry-After seconds (30 by default)" ;;
4??) echo "$BODY" | jq '.error.type, .error.message' ;;
5??) echo "api_error — retry with backoff" ;;
esac限制
- 每个 API 密钥每分钟 600 次请求 (固定窗口;各套餐限制相同)
- 429 响应包含 Retry-After: 30 秒
- 单张图片最大 10 MB
- 格式:: JPEG, PNG, WebP
- 各套餐并发批处理数:: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
- 仅支持轮询 — API 不发送 Webhook。
为什么 cURL 仍是验证 API 最快的方式
- 零安装——各大主流操作系统均内置 cURL
- 与 jq 配合实现脚本化流水线(CI、cron、shell 钩子)
- 在将 endpoint 接入代码之前对其进行冒烟测试的最快方法
- 本页中的每条命令均可直接粘贴至任何 POSIX shell 运行
局限性与不支持的场景
- 轮询循环会阻塞终端——如需并行 worker 请改用 Node 或 Python
- 轮询是唯一的完成信号;API 不发送 webhook
- Windows 命令提示符用户应运行 WSL 或 PowerShell 的 curl.exe
开发者常见问题
是否有 Photta CLI 工具?
目前还没有——但 cURL 加上一个 15 行的 bash 包装脚本就能满足大部分需求。文档优先采用 cURL 示例,因为任何语言都可以运行子进程,而且 shell 是 CI 流水线中的通用语言。
使用该 API 必须用 jq 吗?
并非硬性要求——但在脚本化流水线中配合使用会轻松得多。jq 允许你直接从 JSON 响应中提取 `.data.id`、`.data.status` 和 `.data.output_url`,无需手动解析。在 macOS 上通过 `brew install jq` 安装,在 Debian/Ubuntu 上通过 `apt install jq` 安装。
如何使用 curl 进行身份验证?
在每个请求中添加 `-H "Authorization: Bearer $PHOTTA_API_KEY"`。请将密钥保存在环境变量中,切勿硬编码到提交的脚本里。`curl --oauth2-bearer` 同样有效,但显式声明请求头的写法在文档和日志中更清晰直观。
我可以在生产环境中使用基于 curl 的脚本吗?
对于单次批量回填和 cron 定时任务,完全可以——成千上万的团队都以此方式上线商品目录回填。对于长期运行的应用程序,使用成熟的编程语言通常更合适,因为你能获得完善的错误处理、重试机制和可观测性。本页上的 curl 示例即使在移植到 Node 或 Python 后依然准确,请求体结构完全一致。
如何通过 bash 循环进行轮询?
使用 `for i in $(seq 1 120); do … ; sleep 3; done`,并在循环体中执行状态检查。当 `.data.status` 变为 `completed` 或 `failed` 时跳出循环。本页的代码示例展示了具体模式,包含严格的执行次数上限,防止卡住的任务导致脚本无限挂起。
如何在 curl 中读取错误响应?
使用 `curl -w "\n%{http_code}"` 可在获取 JSON 响应体的同时捕获 HTTP 状态码。根据状态码进行分支处理:402 表示 credits 不足,429 表示达到 rate limit(请遵循 Retry-After 数值),5xx 表示临时服务器错误。错误体中始终包含 `error.code` 和 `error.message` 字段。
相关页面
Node.js
在 Node.js 中使用 幽灵模特 API
在 Node.js 后端中使用原生 fetch 调用 Photta 的 幽灵模特 API。无需 SDK:存储你的 key、提交任务、轮询获取结果即可。
阅读Python
Python 中的 幽灵模特 API
在 Python 中使用 requests 库调用 Photta 的 幽灵模特 API。三十行包装函数,通过 httpx 具备异步亲和性,可在 Django、FastAPI 和 Celery 中开箱即用。
阅读功能特性
幽灵模特 API 适用于镂空模特商品图
AI 幽灵模特 endpoint。从服装照片中移除模特,完整保留内部细节。支持 3D 或平铺效果,支持批量处理,2K 分辨率 4 credits。
阅读构建
为您的商品目录实现隐形模特自动提取
每晚目录自动化配方:拉取昨天的商品更新,批量提交至 Photta 的隐形模特 API,轮询父批次,持久化存储到您的数据库。
阅读快速开始
5 分钟内生成第一张 Photta 图像。
注册、生成 API 密钥、运行第一个 cURL 调用、轮询直至完成、持久化保存结果。共五个步骤,端到端完整记录。
阅读参考
Photta API 定价
Photta API 各个 endpoint 在 2K 和 4K 分辨率下的 credits 成本、扣费与退款机制,以及哪些 endpoint 是免费的。没有按单张图片收取的货币价格。
阅读
本页所有数据均来自 Photta API 文档 · 已验证
五分钟内上手试用 API
生成 Photta API key,粘贴上方的 cURL 代码片段,咖啡还没煮好,你的第一张模特实穿图就已经生成完毕。
- 1.5–4 min
- 2K 分辨率 4 credits · 4K 分辨率 5 credits
- 异步,轮询
- 600 次请求/分钟
- Bearer key