功能 · 批量隐形模特

批量隐形模特 API 适用于完整商品目录

一句话总结

Photta 的批量隐形模特 endpoint 接收服装照片数组，并返回一个批次 id 以及每张图像对应的项目 id。整批所需的 credits 会在前期预扣；轮询该批次即可获取聚合状态。

获取 API Key阅读文档
  • 常规耗时: 1.5–4 min per image
  • Credits: 2K 分辨率 4 credits · 4K 分辨率 5 credits
  • 处理方式: 异步，轮询
  • 限制: 600 次请求/分钟
  • 身份验证: Bearer key

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

POST/api/v1/ghost-mannequin/batch
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin/batch \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_images": [
    {
      "image": "https://cdn.yourstore.com/products/jacket-front.jpg",
      "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
      "image_side": "front"
    },
    {
      "image": "https://cdn.yourstore.com/products/shirt-front.jpg",
      "image_side": "front"
    },
    {
      "image": "https://cdn.yourstore.com/products/trousers-front.jpg",
      "image_side": "front"
    }
  ],
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, buttoned up",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
A garment shown without its mannequin by the ghost mannequin API
示例输出

概览

概览

端点
POST /api/v1/ghost-mannequin/batch
身份验证
Bearer API 密钥
处理方式
异步 — 轮询状态端点
常规耗时
1.5–4 min per image
Credits
2K 分辨率 4 credits · 4K 分辨率 5 credits
宽高比
3:4 · 1:1 · 4:3 · 9:16 · 16:9
输入限制
单张图片最大 10 MB；支持 JPEG, PNG, WebP
幂等性
否

请求与响应

请求

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin/batch \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_images": [
    {
      "image": "https://cdn.yourstore.com/products/jacket-front.jpg",
      "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
      "image_side": "front"
    },
    {
      "image": "https://cdn.yourstore.com/products/shirt-front.jpg",
      "image_side": "front"
    },
    {
      "image": "https://cdn.yourstore.com/products/trousers-front.jpg",
      "image_side": "front"
    }
  ],
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, buttoned up",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / 已完成

{
  "data": {
    "batch_id": "gmb_x7y8z9",
    "status": "processing",
    "total": 3,
    "completed": 0,
    "failed": 0,
    "items": [
      {
        "id": "gm_p1q2r3",
        "status": "processing"
      },
      {
        "id": "gm_s4t5u6",
        "status": "processing"
      },
      {
        "id": "gm_v7w8x9",
        "status": "processing"
      }
    ],
    "style": "3d",
    "background_color": "white",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_reserved": 12,
    "created_at": "2026-04-10T16:05:00Z"
  },
  "request_id": "req_gmb001"
}

请求参数

product_images

类型: array[object]必填

Array of image objects. Each object contains "image" (URL or base64), optional "back_image", and optional "image_side". API batch caps (5× the dashboard limit): Free/Hobby/Hobby v2 5, Seller/Starter 10, Brand/Pro 25, Studio/Premium 50.

angle

类型: string

Applied to all images. "side" reconstructs the side view from each front photo (plus back_image when provided) — see the single-generate endpoint for details.

= straight

取值: straightbackside
style

类型: string

Applied to all images.

= 3d

取值: 3dflat_lay
background_color

类型: string

Applied to all images.

= white

取值: whitegraybeigeblack
resolution

类型: string

Applied to all images. "2K" = 4 credits each. "4K" = 5 credits each. 4K is produced natively in a single generation per item — pick it upfront; the resolution cannot be changed after creation. Note: 4K cannot be combined with aspect_ratio 1:1 — that combination returns 400.

= 2K

取值: 2K4K
aspect_ratio

类型: string

Applied to all images. Note: 1:1 is not available at 4K resolution — 1:1 combined with 4K returns 400.

= 3:4

取值: 3:41:14:39:1616:9
user_instruction

类型: string

Batch-level: one note applied to every item. Optional free-form string, max 400 characters (anything longer is silently truncated). A guarded steer for ambiguous rendering choices — e.g. "closed front", "cream interior lining", "buttoned up" — it never overrides the source garment, brand label, or structural reconstruction, and it is explicitly NOT a determinism/seed control.

brand_label_id

类型: string

Applied to all images. Brand label UUID returned by the Brand Labels API. API v1 request fields use snake_case; use brand_label_id.

错误

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_images` 中每件服装对应一个对象：包含 `image`，以及可选的 `back_image` 和 `image_side`。API 批次上限为：Free 和 Hobby 方案 5 张，Seller 方案 10 张，Brand 方案 25 张，Studio 方案 50 张。

  3. 步骤 3

    POST 提交批次

    POST `/api/v1/ghost-mannequin/batch`。`angle`、`style`、`background_color`、`resolution` 和 `aspect_ratio` 应用于所有项目，`user_instruction` 可为全部项目添加一条最多 400 字符的说明。整批的 credits 会在首个项目渲染前完成预扣。

  4. 步骤 4

    轮询批次

    每 3 秒 GET `/api/v1/ghost-mannequin/batch/:id`。响应体包含 `total`、`completed`、`failed` 以及逐项明细，你可以在最后一件服装渲染完成前就开始下载。

  5. 步骤 5

    下载各项结果

    每个完成的项目都包含各自的 `output_url`、`credits_used` 和耗时。失败的项目会退还其预扣的 credits，并记录在 `credits_refunded` 中。

同一个 endpoint 在 Node.js、Python 和 cURL 中的实现

开发者运行批次前的常见问题

批量 endpoint 带来了什么？

它允许在单次请求中传入服装照片数组并在后台处理。你将获得用于查看整体进度的批次 id 以及对应每张照片的项目 id，无需单独追踪数十个独立任务。

一个批次最多可容纳多少张图像？

API 批次上限为：Free 和 Hobby 方案 5 张，Seller 方案 10 张，Brand 方案 25 张，Studio 方案 50 张——是控制台限制的五倍。提交超出方案允许额度的批次将返回 400。

批次如何扣除 credits？

整批费用会在前期预扣：图像数量乘以单张单价，2K 为 4 credits，4K 为 5 credits。若余额不足以支付预扣金额，请求将返回 402 且不会渲染任何内容。

当其中一个项目失败时会发生什么？

批次中的其余项目会继续执行。批次响应体会同时返回 `failed` 与 `completed` 数量，失败项目预扣的 credits 会通过 `credits_refunded` 返还。

可以同时运行多少个批次？

进行中的并发批次受方案限制：Free 为 1，Hobby 为 2，Seller 为 3，Brand 为 4，Studio 为 6。超出上限提交将返回 409——请持续轮询进行中的批次直至其结束，然后再重新提交。

如何轮询批次？

每 3 秒 GET `/api/v1/ghost-mannequin/batch/:id` 获取聚合状态，或在需要获取单件服装的详细信息时，通过标准隐形模特状态路径轮询任意单个项目。

相关功能

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

五分钟内上手试用 API

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

创建账户并获取 API Key阅读文档
  • 1.5–4 min per image
  • 2K 分辨率 4 credits · 4K 分辨率 5 credits
  • 异步，轮询
  • 600 次请求/分钟
  • Bearer key