Capability · 幽灵模特

幽灵模特 API 适用于镂空模特商品图

一句话总结

Photta 的幽灵模特 API 接收模特穿着服装的照片，返回服装内部结构已重建的隐形模特图像。选择 3d 或 flat_lay 风格，发送 POST 请求，每 3 秒轮询一次，完成后下载即可。

常规耗时: 1.5–4 min
Credits: 2K 分辨率 4 credits · 4K 分辨率 5 credits
处理方式: 异步，轮询
限制: 600 次请求/分钟
身份验证: Bearer key

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

POST/api/v1/ghost-mannequin

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

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

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

A garment shown without its mannequin by the ghost mannequin API — 示例输出

概览

端点: 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
幂等性: 否

请求与响应

请求

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

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

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

202 Accepted / 已完成

{
  "data": {
    "id": "gm_d4e5f6",
    "status": "processing",
    "style": "3d",
    "angle": "side",
    "background_color": "white",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 4,
    "created_at": "2026-04-10T16:00:00Z"
  },
  "request_id": "req_gm001"
}

{
  "data": {
    "id": "gm_d4e5f6",
    "status": "completed",
    "style": "3d",
    "angle": "side",
    "background_color": "white",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "output_url": "https://cdn.photta.app/generated/gm_d4e5f6.jpg",
    "thumbnail_url": "https://cdn.photta.app/generated/gm_d4e5f6-thumb.jpg",
    "credits_used": 4,
    "created_at": "2026-04-10T16:00:00Z",
    "completed_at": "2026-04-10T16:00:48Z",
    "duration_ms": 48000
  },
  "request_id": "req_gm002"
}

请求参数

字段描述

product_image

类型: string必填

URL or base64 data URI of the garment photo (front or back, on a mannequin or flat).

back_image

类型: string

URL or base64 data URI of the opposite side — helps the AI reconstruct the interior of the garment for a more realistic 3D effect.

image_side

类型: string

Which side product_image represents.

= front

frontback

angle

类型: string

Camera angle for the output. "side" is worth calling out: the side view is reconstructed from the front photo (plus the back photo when provided), giving you a third catalog view without a third photoshoot — and it works well even on textured garments (crochet, lace, embroidery).

= straight

straightbackside

style

类型: string

Output style: "3d" (ghost mannequin with 3D body shape) or "flat_lay" (garment laid flat, mannequin removed).

= 3d

3dflat_lay

background_color

类型: string

Background color.

= white

whitegraybeigeblack

resolution

类型: string

Output resolution. "2K" costs 4 credits per image; "4K" costs 5 credits per image. 4K is produced natively in a single generation — 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

Output aspect ratio. 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

Optional free-form note, 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

Brand label UUID returned by the Brand Labels API. Applied to the generated garment when present. 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
生成 API key
隐形模特功能与 Photta 的其他功能共用相同的凭证——一个 key，一个 credits 余额。
步骤 2
上传原图
在 `product_image` 中传入公开 URL 或 base64 data URI；如果有背面视角，可添加 `back_image`。支持 JPEG、PNG 和 WebP，每张图片最大 10 MB。
步骤 3
POST 提交隐形模特任务
向 `/api/v1/ghost-mannequin` 发送 POST 请求，附带 `product_image`、`style`（`3d` 或 `flat_lay`），可选参数包括 `angle`、`background_color`、`resolution`。轮询是唯一的完成信号——API 不发送 webhook。
步骤 4
轮询直至任务完成
每隔 3 秒 GET 一次 `/api/v1/ghost-mannequin/:id`，直到 `data.status` 变为 `completed` 或 `failed`；通常耗时 1.5 到 4 分钟完成。
步骤 5
下载并持久化存储
输出格式为移除了模特并重建了服装内衬结构的 PNG 图片。非常适合 PDP 隐形模特展示图、具立体感的产品图册以及平铺细节图插入。

在 Node.js、Python 和 cURL 中调用相同的 endpoint

开发者上线隐形模特功能前的常见问题

什么是隐形模特摄影（Ghost Mannequin）？

一种 PDP 商品展示手法，服装仿佛穿在一个隐形人体上，能同时呈现轮廓版型与内部构造。传统上这需要多张影棚拍摄照片拼接而成；Photta 的 API 仅需单次调用，输入一张模特原图即可生成。

隐形模特功能如何计费？

2K 分辨率 4 credits，4K 分辨率 5 credits——每个档位都比 try-on 便宜 1 credit。失败的任务会自动退款。

3D 与平铺（flat-lay）风格有什么区别？

`3d` 风格保留了模特的三维人身轮廓——服装保持立体感，肩部与袖口形态自然，且内衬结构经过重建。`flat_lay` 则将服装平展为利落的 2D 布局，非常适合胶囊系列或需要统一正面构图的电商平台展示。

支持批量处理多张照片吗？

支持。向 `/api/v1/ghost-mannequin/batch` 发送 POST 请求并传入原图数组。响应将返回一个 batch ID 以及各个子项的生成 ID。通过轮询 `/api/v1/ghost-mannequin/batch/:id` 可获取总体状态，也可以单独轮询每个子项。

内衬接缝和领标会被保留吗？

是的——模型会重建服装内部（领口内侧、袖口内衬、腰头衬里），而非凭空生成通用表面。原图上清晰可见的吊牌和印花标签会尽可能予以保留。

如何轮询获取结果？

每隔 3 秒 GET 一次 `/api/v1/ghost-mannequin/:id`。批量任务则轮询父级 endpoint，它会返回总体状态及各子项详情。

五分钟内上手试用 API

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

创建账户并获取 API Key 阅读文档

1.5–4 min
2K 分辨率 4 credits · 4K 分辨率 5 credits
异步，轮询
600 次请求/分钟
Bearer key

幽灵模特 API 适用于镂空模特商品图

概览

请求与响应

请求参数

错误

输入单张照片，输出隐形模特效果图

生成 API key

上传原图

POST 提交隐形模特任务

轮询直至任务完成

下载并持久化存储

在 Node.js、Python 和 cURL 中调用相同的 endpoint

开发者上线隐形模特功能前的常见问题

相关功能

五分钟内上手试用 API