功能 · 细节图
商品细节图 API 用于特写
一句话总结
Photta 的细节图 API 可渲染商品指定区域的特写。免费的 analyze 调用可建议值得拍摄的细节;generate 调用单价固定为 3 credits,无分辨率分档。
- 常规耗时: 20–60 sec
- Credits: 3 credits
- 处理方式: 异步,轮询
- 限制: 600 次请求/分钟
- 身份验证: Bearer key
本页所有数据均来自 Photta API 文档 · 已验证
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
"detail_label": "collar stitching",
"detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
"framing": "extreme-closeup",
"source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/detail-photos", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
"detail_label": "collar stitching",
"detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
"framing": "extreme-closeup",
"source_type": "apparel"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/detail-photos",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
"detail_label": "collar stitching",
"detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
"framing": "extreme-closeup",
"source_type": "apparel"
},
)
data = res.json()["data"] # data["id"], data["status"]概览
概览
- 端点
- POST /api/v1/detail-photos
- 身份验证
- Bearer API 密钥
- 处理方式
- 异步 — 轮询状态端点
- 常规耗时
- 20–60 sec
- Credits
- 3 credits
- 输入限制
- 单张图片最大 10 MB;支持 JPEG, PNG, WebP
- 幂等性
- 否
请求与响应
请求
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
"detail_label": "collar stitching",
"detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
"framing": "extreme-closeup",
"source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/detail-photos", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
"detail_label": "collar stitching",
"detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
"framing": "extreme-closeup",
"source_type": "apparel"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/detail-photos",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
"detail_label": "collar stitching",
"detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
"framing": "extreme-closeup",
"source_type": "apparel"
},
)
data = res.json()["data"] # data["id"], data["status"]202 Accepted / 已完成
{
"data": {
"id": "dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10",
"status": "processing",
"detail_label": "collar stitching",
"framing": "extreme-closeup",
"credits_used": 3,
"created_at": "2026-07-30T14:20:00Z"
},
"request_id": "req_dtl001"
}{
"data": {
"id": "dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10",
"status": "completed",
"detail_label": "collar stitching",
"framing": "extreme-closeup",
"output_url": "https://cdn.photta.app/generated/dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10-thumb.jpg",
"credits_used": 3,
"created_at": "2026-07-30T14:20:00Z",
"completed_at": "2026-07-30T14:20:42Z",
"duration_ms": 42000
},
"request_id": "req_dtl003"
}请求参数
product_image类型: string必填
The source image — a completed generation's output_url or any product photo. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.
detail_label类型: string必填
The area to zoom into, e.g. "collar stitching", "cuff detail", "fabric weave on the chest", "pendant clasp". Max 100 characters.
detail_description类型: string
Extra guidance for the close-up. Max 400 characters.
framing类型: string
How tight the crop is: "extreme-closeup" — the detail fills ~90% of the frame (near-macro); "closeup" — ~70% with some surrounding context; "medium-closeup" — ~50% with body/outfit visible.
= medium-closeup
取值:extreme-closeupcloseupmedium-closeupsource_type类型: string
Tunes what is preserved in the close-up.
= apparel
取值:appareljewelry
错误
- 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.
限制
- 每个 API 密钥每分钟 600 次请求 (固定窗口;各套餐限制相同)
- 429 响应包含 Retry-After: 30 秒
- 单张图片最大 10 MB
- 格式:: JPEG, PNG, WebP
- 各套餐并发批处理数:: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
- 仅支持轮询 — API 不发送 Webhook。
查询值得拍摄的内容,然后进行拍摄
免费分析,选择细节,提交,轮询,下载。
步骤 1
生成 API key
细节图与 Photta 的其他所有功能使用相同的凭据和相同的 credit 余额。
步骤 2
查询要拍摄哪些细节
携带 `product_image` 调用 POST `/api/v1/detail-photos/analyze`。它会同步返回针对该商品的建议 `detail_label`、`detail_description` 和 `framing` 值,不产生费用。
步骤 3
POST 特写任务
携带 `product_image` 和 `detail_label` 调用 POST `/api/v1/detail-photos`。将 `framing` 设置为 `extreme-closeup`、`closeup` 或 `medium-closeup`,`source_type` 设置为 `apparel` 或 `jewelry`,并添加最多 400 个字符的 `detail_description`。
步骤 4
轮询直到任务完成
每 3 秒调用一次 GET `/api/v1/detail-photos/:id`,直到 `data.status` 变为 `completed` 或 `failed`;通常耗时 20 到 60 秒。
步骤 5
下载并持久化存储
完成的响应体包含 `output_url`。细节图可直接插入 PDP 画廊,紧挨主图展示。
Node.js、Python 和 cURL 中的相同 endpoint
Node.js
在 Node.js 中使用 商品细节图 API
在 Node.js 后端中使用原生 fetch 调用 Photta 的 商品细节图 API。无需 SDK:存储你的 key、提交任务、轮询获取结果即可。
阅读Python
Python 中的 商品细节图 API
在 Python 中使用 requests 库调用 Photta 的 商品细节图 API。三十行包装函数,通过 httpx 具备异步亲和性,可在 Django、FastAPI 和 Celery 中开箱即用。
阅读cURL
通过 cURL 调用 商品细节图 API
直接在终端中使用 cURL 调用 Photta 的 商品细节图 API。提交、轮询、下载——每个代码片段均可搭配 jq 用于自动化流水线脚本。
阅读
开发者上线细节图前常问的问题
什么是细节图 API?
一个通过单张较广视角的照片渲染商品指定区域特写(如衣领缝线、搭扣、胸前织法)的 endpoint,无需使用微距镜头进行二次影棚拍摄。
细节图的费用是多少?
固定 3 credits。该 endpoint 没有分辨率分档,且提供细节建议的 analyze 调用是免费的。
analyze endpoint 返回什么内容?
一份建议列表,每条建议均包含一个 `detail_label`、一个解释该区域为何值得展示的 `detail_description` 以及一个推荐的 `framing`。任何建议都可直接传入 generate 调用。
各 framing 选项的景别有多紧?
`extreme-closeup` 几乎让细节占满整个画面,`closeup` 保留少量周围上下文,而 `medium-closeup` 则展示细节及其周围的服装或部件。请按具体细节而非按商品进行选择。
源图可以是生成的图像吗?
支持。`product_image` 既支持已完成生成的 `output_url`,也支持你自己的任意商品图,格式可为 https URL 或 base64 data URI。
如何轮询获取结果?
每隔 3 秒 GET `/api/v1/detail-photos/:id`,直到 `data.status` 为 `completed` 或 `failed`。分析接口调用是同步的,无需轮询。
相关功能
功能特性
虚拟 try-on API 适用于服装
将服装穿在 AI 模特身上的 REST API。异步处理,1.5–4 分钟生成耗时,2K 分辨率 5 credits,4K 分辨率 6 credits。提供 cURL、Node.js 与 Python 示例代码。
查看 endpoint功能特性
首饰试穿 API 适用于项链、戒指、手链和耳环
通过 REST 将项链、戒指、手链和耳环穿戴至 AI 模特身上。2K 规格单次 5 credits,内置特写模特,具备 Photta 文档所述的反光感知渲染能力。
查看 endpoint构建
构建 AI 商品摄影服务
创始人将 Photta 虚拟 try-on API 作为白标 SaaS 转售的实战指南:租户 key、批量扇出、按 credit 计费以及 SLA 现实考量。
查看 endpoint对比
Photta vs FASHN — 时尚 AI API 横向对比
Photta 与 FASHN 全方位对比:endpoint、credits 定价、方案层级、并发限制。数据均来自两家公司于 2026-04-19 的公开定价页面。绝无虚构数字。
查看 endpoint快速开始
5 分钟内生成第一张 Photta 图像。
注册、生成 API 密钥、运行第一个 cURL 调用、轮询直至完成、持久化保存结果。共五个步骤,端到端完整记录。
查看 endpoint参考
Photta API 错误
Photta API 错误类型的完整列表及其状态码、错误响应体的结构,以及哪些失败情况值得重试。
查看 endpoint参考
Photta API 速率限制
Photta API 的速率限制、时间窗口、Retry-After 请求头、轮询间隔以及各套餐的并发上限,均取自官方 API 文档。
查看 endpoint
本页所有数据均来自 Photta API 文档 · 已验证
五分钟内上手试用 API
生成 Photta API key,粘贴上方的 cURL 代码片段,咖啡还没煮好,你的第一张模特实穿图就已经生成完毕。
- 20–60 sec
- 3 credits
- 异步,轮询
- 600 次请求/分钟
- Bearer key