功能 · Workflows

Workflows API 单次调用,单个预设

一句话总结

Photta 的 workflows API 针对您的商品图像运行现成场景模板。获取目录,填入工作流声明的图像插槽与配置项,发起 POST 请求,然后轮询返回的各个条目直至完成。

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

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

POST/api/v1/workflows/{workflow_id}
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')

概览

概览

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

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

请求参数

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:9
resolution

类型: string

Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.

= 2K

取值: 2K4K

错误

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

    Workflows 与 Photta 的所有其他功能共享相同的凭证和 credit 余额。

  2. 步骤 2

    获取工作流目录列表

    GET `/api/v1/workflows` 返回 7 个类别下的 53 个模板,每个模板均声明了其自有的图像插槽、选项枚举以及默认宽高比。可通过 `category` 过滤——传入未知类别会返回 400 而非直接忽略。

  3. 步骤 3

    POST 提交运行任务

    向 `/api/v1/workflows/:workflow_id` 发起 POST 请求,携带 `images`(插槽 id 对应图像)和 `options`(选项 id 对应选择项 id),两者均取自目录条目。`user_text` 接收自定义风格提示文本,`num_images` 支持单次调用生成 1 到 4 张图像。

  4. 步骤 4

    轮询每个条目

    202 响应中每个请求的图像对应一个条目。针对每个 id 每 3 秒 GET 一次 `/api/v1/workflows/generations/:id`,直到 `data.status` 变为 `completed` 或 `failed`;单张图像通常在 20 到 60 秒内完成。

  5. 步骤 5

    下载并持久化保存

    每个完成的条目均带有独立的 `output_url`。各条目相互独立完成渲染,您可以在其余图像仍在生成时直接发布首张已完成的图像。

开发者在运行工作流前常问的问题

什么是 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` 过滤的分页视图。

相关功能

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

五分钟内上手试用 API

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

  • 20–60 sec / image
  • 2K 分辨率 4 credits · 4K 分辨率 5 credits
  • 异步,轮询
  • 600 次请求/分钟
  • Bearer key