Tính năng · Workflows

Workflows API một lệnh gọi, một preset

Tóm tắt trong một câu

Workflows API của Photta chạy các mẫu bối cảnh dựng sẵn với hình ảnh sản phẩm của bạn. Lấy danh mục, điền các vị trí hình ảnh và tùy chọn của workflow, POST, sau đó polling từng mục được trả về cho đến khi hoàn tất.

  • Thời gian điển hình: 20–60 sec / image
  • Credits: 4 credits ở 2K · 5 credits ở 4K
  • Xử lý: async, polling
  • Giới hạn: 600 requests/min
  • Xác thực: Bearer key

Mọi số liệu trên trang này đều lấy từ tài liệu Photta API · đã kiểm tra

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

Tổng quan nhanh

Tổng quan nhanh

Endpoint
POST /api/v1/workflows/{workflow_id}
Xác thực
Bearer API key
Xử lý
Bất đồng bộ — polling status endpoint
Thời gian điển hình
20–60 sec / image
Credits
4 credits ở 2K · 5 credits ở 4K
Tỷ lệ khung hình
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Giới hạn đầu vào
Tối đa 10 MB mỗi ảnh; JPEG, PNG, WebP
Idempotent
Không

Request và response

Request

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 / Completed

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

Tham số request

workflow_id

Kiểu: stringBắt buộc

The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.

images

Kiểu: objectBắt buộc

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

Kiểu: 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

Kiểu: 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

Kiểu: integer

Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.

= 1

aspect_ratio

Kiểu: string

Output aspect ratio. Defaults to the workflow's default_aspect_ratio from the catalog (3:4 for every current workflow).

= 3:4

Giá trị: 3:41:14:39:1616:9
resolution

Kiểu: string

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

= 2K

Giá trị: 2K4K

Lỗi

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.

Giới hạn

  • 600 request mỗi phút trên mỗi API key (Fixed window; giới hạn như nhau trên mọi gói)
  • Mã 429 kèm header Retry-After: 30 giây
  • Tối đa 10 MB mỗi ảnh
  • Định dạng: JPEG, PNG, WebP
  • Batch đồng thời theo từng gói: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Chỉ hỗ trợ polling — API không gửi webhook.

Lấy danh mục, điền các vị trí, chạy

Liệt kê các workflow, điền các vị trí được khai báo của chúng, gửi, polling từng mục, tải về.

  1. Bước 1

    Tạo một API key

    Workflows sử dụng cùng thông tin xác thực và cùng số dư credits như mọi tính năng khác của Photta.

  2. Bước 2

    Liệt kê danh mục workflow

    GET `/api/v1/workflows` trả về 53 mẫu thuộc 7 danh mục, mỗi mẫu khai báo các vị trí hình ảnh, enum tùy chọn và tỷ lệ khung hình mặc định riêng. Lọc bằng `category` — danh mục không xác định sẽ trả về 400 thay vì bị bỏ qua.

  3. Bước 3

    POST lượt chạy

    POST `/api/v1/workflows/:workflow_id` với `images` (slot id ánh xạ tới hình ảnh) và `options` (option id ánh xạ tới choice id), cả hai đều lấy từ mục trong danh mục. `user_text` chấp nhận yêu cầu định kiểu dạng văn bản tự do, và `num_images` chạy từ 1 đến 4 hình ảnh trong một lệnh gọi.

  4. Bước 4

    Polling từng mục

    Phản hồi 202 mang một mục cho mỗi hình ảnh được yêu cầu. GET `/api/v1/workflows/generations/:id` mỗi 3 giây cho từng id cho đến khi `data.status` là `completed` hoặc `failed`; thời gian hoàn tất thông thường là 20 đến 60 giây mỗi hình ảnh.

  5. Bước 5

    Tải về và lưu trữ lâu dài

    Mỗi mục hoàn tất mang `output_url` riêng. Các mục hoàn tất độc lập, vì vậy bạn có thể xuất bản mục đầu tiên trong khi các mục còn lại vẫn đang render.

Các câu hỏi lập trình viên đặt ra trước khi chạy workflows

Workflows API là gì?

Một danh mục các mẫu bối cảnh dựng sẵn mà bạn chạy với ảnh chụp sản phẩm của chính mình. Thay vì phải dựng prompt, bạn chọn một workflow và điền vào các vị trí hình ảnh cùng các tùy chọn mà nó khai báo.

Một lượt chạy workflow có giá bao nhiêu?

4 credits mỗi hình ảnh ở 2K và 5 mỗi hình ảnh ở 4K, nhân với `num_images`. Danh mục mang giá trực tiếp cho từng workflow — hãy đọc giá từ đó thay vì tự giả định.

Làm thế nào để tìm workflow id?

GET `/api/v1/workflows`. Mỗi mục chứa id, category, các vị trí hình ảnh và các tùy chọn của nó. Lọc danh sách bằng `category`: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` hoặc `watch`.

Dữ liệu nào được đưa vào images và options?

`images` ánh xạ slot id từ mục trong danh mục sang một mảng hình ảnh, dưới dạng URL https hoặc base64 data URI. `options` ánh xạ option id sang một trong các choice id của tùy chọn đó. Cả hai cấu trúc đều lấy từ danh mục, đó là lý do bản tích hợp vẫn hoạt động tốt khi có thêm workflows mới.

Một lượt chạy có thể tạo ra bao nhiêu hình ảnh?

`num_images` chấp nhận từ 1 đến 4. Mỗi hình ảnh được tạo độc lập và nhận item id riêng trong phản hồi, vì vậy một hình ảnh thất bại sẽ không làm ảnh hưởng đến các hình ảnh khác.

Làm thế nào để polling các kết quả?

Poll từng item riêng lẻ: GET `/api/v1/workflows/generations/:id` mỗi 3 giây một lần. GET `/api/v1/workflows/generations/list` trả về danh sách phân trang được lọc theo `workflow_id` hoặc `status`.

Các tính năng liên quan

Mọi số liệu trên trang này đều lấy từ tài liệu Photta API · đã kiểm tra

Thử nghiệm API trong năm phút

Tạo một Photta API key, dán đoạn mã cURL ở trên, và bạn sẽ nhận được bức ảnh mẫu mặc đồ đầu tiên trước khi pha xong ly cà phê.

  • 20–60 sec / image
  • 4 credits ở 2K · 5 credits ở 4K
  • async, polling
  • 600 requests/min
  • Bearer key