功能 · Workflows
Workflows API 单次调用,单个预设
一句话总结
Photta 的 workflows API 针对您的商品图像运行现成场景模板。获取目录,填入工作流声明的图像插槽与配置项,发起 POST 请求,然后轮询返回的各个条目直至完成。
- 常规耗时: 20–60 sec / image
- Credits: 2K 分辨率 4 credits · 4K 分辨率 5 credits
- 处理方式: 异步,轮询
- 限制: 600 次请求/分钟
- 身份验证: Bearer key
本页所有数据均来自 Photta API 文档 · 已验证
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/workflows/jewelry-studio-shot \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/workflows/jewelry-studio-shot", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/workflows/jewelry-studio-shot",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
},
)
data = res.json()["data"] # data["id"], data["status"]概览
概览
- 端点
- POST /api/v1/workflows/{workflow_id}
- 身份验证
- Bearer API 密钥
- 处理方式
- 异步 — 轮询状态端点
- 常规耗时
- 20–60 sec / 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/workflows/jewelry-studio-shot \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/workflows/jewelry-studio-shot", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/workflows/jewelry-studio-shot",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
},
)
data = res.json()["data"] # data["id"], data["status"]202 Accepted / 已完成
{
"data": {
"items": [
{
"id": "wfl_1f7c03a9e5b2486dd90c4b17ae62f508",
"workflow_id": "jewelry-studio-shot",
"status": "processing",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z"
},
{
"id": "wfl_8b2d64f0a1c9573ee4082d6cb95a3f17",
"workflow_id": "jewelry-studio-shot",
"status": "processing",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z"
}
],
"workflow_id": "jewelry-studio-shot",
"workflow_version": 1,
"credits_used": 8
},
"request_id": "req_wfl002"
}{
"data": {
"id": "wfl_1f7c03a9e5b2486dd90c4b17ae62f508",
"workflow_id": "jewelry-studio-shot",
"status": "completed",
"output_url": "https://cdn.photta.app/generated/wfl_1f7c03a9e5b2486dd90c4b17ae62f508.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/wfl_1f7c03a9e5b2486dd90c4b17ae62f508-thumb.jpg",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z",
"completed_at": "2026-08-03T10:20:41Z",
"error_code": null,
"error_message": null
},
"request_id": "req_wfl003"
}请求参数
workflow_id类型: string必填
The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.
images类型: object必填
Map of image slot id → array of images (https URL or base64 data URI). Slot ids, required flags, and min/max image counts come from the workflow's image_slots in the catalog. Missing entirely, missing a required slot, using an unknown slot, or exceeding a slot's max_images returns 400.
options类型: object
Map of option id → choice id, both from the workflow's options in the catalog. Omitted options use their default_choice. Unknown option ids or choice ids return 400, as does sending an option that a filled image slot replaces (see replaces_options).
user_text类型: string
Free-text styling/framing request (e.g. "hero shot, slightly angled"). Max 500 characters — excess is silently truncated. It never overrides product fidelity: the product always stays true to your images.
num_images类型: integer
Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.
= 1
aspect_ratio类型: string
Output aspect ratio. Defaults to the workflow's default_aspect_ratio from the catalog (3:4 for every current workflow).
= 3:4
取值:3:41:14:39:1616:9resolution类型: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
取值:2K4K
错误
- 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
Workflows 与 Photta 的所有其他功能共享相同的凭证和 credit 余额。
步骤 2
获取工作流目录列表
GET `/api/v1/workflows` 返回 7 个类别下的 53 个模板,每个模板均声明了其自有的图像插槽、选项枚举以及默认宽高比。可通过 `category` 过滤——传入未知类别会返回 400 而非直接忽略。
步骤 3
POST 提交运行任务
向 `/api/v1/workflows/:workflow_id` 发起 POST 请求,携带 `images`(插槽 id 对应图像)和 `options`(选项 id 对应选择项 id),两者均取自目录条目。`user_text` 接收自定义风格提示文本,`num_images` 支持单次调用生成 1 到 4 张图像。
步骤 4
轮询每个条目
202 响应中每个请求的图像对应一个条目。针对每个 id 每 3 秒 GET 一次 `/api/v1/workflows/generations/:id`,直到 `data.status` 变为 `completed` 或 `failed`;单张图像通常在 20 到 60 秒内完成。
步骤 5
下载并持久化保存
每个完成的条目均带有独立的 `output_url`。各条目相互独立完成渲染,您可以在其余图像仍在生成时直接发布首张已完成的图像。
同一个 endpoint 在 Node.js、Python 和 cURL 下的调用方式
Node.js
在 Node.js 中使用 Workflows API
在 Node.js 后端中使用原生 fetch 调用 Photta 的 workflows API。无需 SDK:存储你的 key、提交任务、轮询获取结果即可。
阅读Python
Python 中的 Workflows API
在 Python 中使用 requests 库调用 Photta 的 workflows API。三十行包装函数,通过 httpx 具备异步亲和性,可在 Django、FastAPI 和 Celery 中开箱即用。
阅读cURL
通过 cURL 调用 Workflows API
直接在终端中使用 cURL 调用 Photta 的 workflows API。提交、轮询、下载——每个代码片段均可搭配 jq 用于自动化流水线脚本。
阅读
开发者在运行工作流前常问的问题
什么是 workflows API?
一个现成场景模板目录,供您针对自己的商品照片运行生成任务。您无需自行拼接 prompt,只需挑选一个工作流并填入其声明的图像插槽和配置项即可。
运行一次工作流的费用是多少?
2K 分辨率下每张图像 4 credits,4K 分辨率下每张图像 5 credits,乘以 `num_images`。目录中包含每个工作流的实时价格——请直接从目录读取,切勿主观预设。
如何获取工作流的 id?
GET `/api/v1/workflows`。每个条目均包含其 id、所属类别、图像插槽和配置选项。可使用 `category` 进行过滤:`jewelry`、`product`、`shoe`、`cosmetics`、`food`、`bag` 或 `watch`。
images 和 options 中应该传什么?
`images` 将目录条目中的插槽 id 映射到图像数组(支持 https URL 或 base64 data URI)。`options` 将选项 id 映射为其有效选项之一的 choice id。两者的结构均由目录定义,因此即便上线新工作流,现有集成也能正常兼容。
单次运行可以生成多少张图像?
`num_images` 接收 1 到 4。每张图像独立生成,并在响应中拥有各自的条目 id,单张失败不会影响其他图像的生成。
如何轮询获取结果?
单独轮询每个项目:每 3 秒 GET `/api/v1/workflows/generations/:id`。GET `/api/v1/workflows/generations/list` 提供按 `workflow_id` 或 `status` 过滤的分页视图。
相关功能
功能特性
虚拟 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 Ayna —— 开发者 API 与 Shopify 优先的工作室套件对比
Photta 与 Ayna 对比:三个 REST endpoint 对比以 Shopify 为核心的 Studio 配合 API。两者各有优势。数据于 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 / image
- 2K 分辨率 4 credits · 4K 分辨率 5 credits
- 异步,轮询
- 600 次请求/分钟
- Bearer key