功能 · 细节图

商品细节图 API 用于特写

一句话总结

Photta 的细节图 API 可渲染商品指定区域的特写。免费的 analyze 调用可建议值得拍摄的细节;generate 调用单价固定为 3 credits,无分辨率分档。

  • 常规耗时: 20–60 sec
  • Credits: 3 credits
  • 处理方式: 异步,轮询
  • 限制: 600 次请求/分钟
  • 身份验证: Bearer key

本页所有数据均来自 Photta API 文档 · 已验证

POST/api/v1/detail-photos
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')

概览

概览

端点
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')

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"
}

请求参数

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-closeup
source_type

类型: string

Tunes what is preserved in the close-up.

= apparel

取值: appareljewelry

错误

400invalid_request_error
The request is malformed or contains invalid parameters.
401authentication_error
The API key is missing, invalid, or expired.
402insufficient_credits_error
Your account does not have enough credits.
404not_found_error
The requested resource does not exist.
409conflict_error
The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error
Too many requests. Slow down and retry.Retry-After: 30
500api_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. 步骤 1

    生成 API key

    细节图与 Photta 的其他所有功能使用相同的凭据和相同的 credit 余额。

  2. 步骤 2

    查询要拍摄哪些细节

    携带 `product_image` 调用 POST `/api/v1/detail-photos/analyze`。它会同步返回针对该商品的建议 `detail_label`、`detail_description` 和 `framing` 值,不产生费用。

  3. 步骤 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. 步骤 4

    轮询直到任务完成

    每 3 秒调用一次 GET `/api/v1/detail-photos/:id`,直到 `data.status` 变为 `completed` 或 `failed`;通常耗时 20 到 60 秒。

  5. 步骤 5

    下载并持久化存储

    完成的响应体包含 `output_url`。细节图可直接插入 PDP 画廊,紧挨主图展示。

开发者上线细节图前常问的问题

什么是细节图 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`。分析接口调用是同步的,无需轮询。

相关功能

本页所有数据均来自 Photta API 文档 · 已验证

五分钟内上手试用 API

生成 Photta API key,粘贴上方的 cURL 代码片段,咖啡还没煮好,你的第一张模特实穿图就已经生成完毕。

  • 20–60 sec
  • 3 credits
  • 异步,轮询
  • 600 次请求/分钟
  • Bearer key