参考 · 资源

Photta API 资源 endpoint 每次生成所需的 id

一句话总结

资源 endpoint 返回生成调用所需的各类 id：人体模型、姿势、背景、鞋履、服装属性和品牌标签，以及您的账户余额和用量。列表查询不产生任何费用。

获取 API Key 阅读文档

资源端点: 13 个资源 endpoint
身份验证: Bearer key
限制: 600 次请求/分钟

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

各个资源 endpoint 及其读取调用方式

每个章节均链接到使用这些 id 的对应能力。

GET/api/v1/mannequins

人体模型

列出可用于服装 try-on 的模型：Photta 系统人体模型、您自行上传的模型，以及通过人体模型生成 API 创建的模型。向同一路径发送 POST 请求可上传自定义人体模型，该模型仅对您的账户私有。获取的 id 填入 try-on 调用的 `mannequin_id` 中。

curl https://api.photta.app/api/v1/mannequins \
  -H "Authorization: Bearer $PHOTTA_API_KEY"

const res = await fetch("https://api.photta.app/api/v1/mannequins", {
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}` },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.photta.app/api/v1/mannequins",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
)
data = res.json()["data"]

虚拟 try-on API

POST/api/v1/mannequins/jewelry

珠宝人体模型

上传用于珠宝 try-on 的特写模型照片。珠宝生成针对颈线、耳朵、手腕或手部进行构图，因此需要专属的人体模型集，而非全身服装模型集。

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/mannequins/jewelry \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "image": "https://cdn.yourstore.com/models/emma-neck.jpg",
  "jewelry_type": "necklace",
  "gender": "female",
  "name": "Emma"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/mannequins/jewelry", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "image": "https://cdn.yourstore.com/models/emma-neck.jpg",
    "jewelry_type": "necklace",
    "gender": "female",
    "name": "Emma"
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/mannequins/jewelry",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "image": "https://cdn.yourstore.com/models/emma-neck.jpg",
      "jewelry_type": "necklace",
      "gender": "female",
      "name": "Emma"
    },
)
data = res.json()["data"]  # data["id"], data["status"]

首饰试穿 API

GET/api/v1/poses

姿势

列出 try-on 可请求的姿势，支持按类目及其适用的产品类型进行过滤。将 id 作为 `pose_id` 传入；若留空，API 会自动选择适合该服装的姿势。

curl https://api.photta.app/api/v1/poses \
  -H "Authorization: Bearer $PHOTTA_API_KEY"

const res = await fetch("https://api.photta.app/api/v1/poses", {
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}` },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.photta.app/api/v1/poses",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
)
data = res.json()["data"]

虚拟 try-on API

GET/api/v1/garment-attributes

服装长度与版型

返回服装 try-on 支持的长度与版型 key。请传递 key 而非自由文本描述，以确保同款衬衫在整个产品目录中渲染出一致的效果。

curl https://api.photta.app/api/v1/garment-attributes \
  -H "Authorization: Bearer $PHOTTA_API_KEY"

const res = await fetch("https://api.photta.app/api/v1/garment-attributes", {
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}` },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.photta.app/api/v1/garment-attributes",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
)
data = res.json()["data"]

虚拟 try-on API

GET/api/v1/backgrounds

背景

列出服装 try-on 的系统背景及您上传的背景，支持游标分页。向同一路径发送 POST 请求可上传自定义背景；该背景仅对您的账户私有。

curl https://api.photta.app/api/v1/backgrounds \
  -H "Authorization: Bearer $PHOTTA_API_KEY"

const res = await fetch("https://api.photta.app/api/v1/backgrounds", {
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}` },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.photta.app/api/v1/backgrounds",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
)
data = res.json()["data"]

眼镜虚拟 try-on API

POST/api/v1/brand-labels

品牌标签

上传用于隐形模特（ghost mannequin）效果的可复用标签图像，并返回一个 id，可作为 `brand_label_id` 传入单个任务或批量任务。GET 请求列出已保存的标签；当达到账户配额上限时，DELETE 请求可用于删除旧标签。

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/brand-labels \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "file": "@/path/to/pribrand-label.png",
  "name": "Pribrand Collar Label"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/brand-labels", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "file": "@/path/to/pribrand-label.png",
    "name": "Pribrand Collar Label"
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/brand-labels",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "file": "@/path/to/pribrand-label.png",
      "name": "Pribrand Collar Label"
    },
)
data = res.json()["data"]  # data["id"], data["status"]

幽灵模特 API

GET/api/v1/footwear

鞋履

列出服装 try-on 的鞋履选项，支持按类型和性别过滤，提供游标分页。用于为穿着指定服装的同一模型搭配鞋履。

curl https://api.photta.app/api/v1/footwear \
  -H "Authorization: Bearer $PHOTTA_API_KEY"

const res = await fetch("https://api.photta.app/api/v1/footwear", {
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}` },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.photta.app/api/v1/footwear",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
)
data = res.json()["data"]

虚拟 try-on API

GET/api/v1/account

账户

按来源明细返回您的 credits 余额、当前方案以及下一次 credits 续期时间。在执行大批量任务前查询该接口，避免因余额不足而遭遇 402 错误。

curl https://api.photta.app/api/v1/account \
  -H "Authorization: Bearer $PHOTTA_API_KEY"

const res = await fetch("https://api.photta.app/api/v1/account", {
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}` },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.photta.app/api/v1/account",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
)
data = res.json()["data"]

Workflows API

GET/api/v1/account/usage

用量

当前自然月计费周期的生成次数与 credits 消耗统计，细分为成功和失败的任务。绘制监控图表时应以该 endpoint 为准，而非自行累计的请求计数。

curl https://api.photta.app/api/v1/account/usage \
  -H "Authorization: Bearer $PHOTTA_API_KEY"

const res = await fetch("https://api.photta.app/api/v1/account/usage", {
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}` },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.photta.app/api/v1/account/usage",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
)
data = res.json()["data"]

批量隐形模特 API

关于资源 endpoint 的常见问题

资源 endpoint 的作用是什么？

它们返回生成调用所需的各类 id —— 人体模型、姿势、背景、品牌标签 —— 以及您的账户状态。该分组下的任何接口均不生成图像。

调用资源接口会消耗 credits 吗？

不会。列表查询完全免费，且该分组下的上传操作（自定义人体模型、背景、品牌标签）同样免费。您只需为实际生成付费。

如何对长列表进行分页？

列表类 endpoint 支持 limit 和游标参数：将上一页最后看到的 id 作为 `starting_after` 传入即可读取下一页。建议缓存获取到的结果，避免在每次请求时重复列出。

我可以上传自己的人体模型和背景吗？

可以。POST `/api/v1/mannequins`、POST `/api/v1/mannequins/jewelry`、POST `/api/v1/backgrounds` 以及 POST `/api/v1/brand-labels` 均支持上传您自己的图像，且您上传的所有内容均对您的账户私有。

这些 id 的使用场景

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

五分钟内上手试用 API

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

创建账户并获取 API Key API

13 个资源 endpoint
Bearer key
600 次请求/分钟