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
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"]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')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 / 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"
}{
"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"
}Tham số request
workflow_idKiể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.
imagesKiể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.
optionsKiể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_textKiể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_imagesKiểu: integer
Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.
= 1
aspect_ratioKiể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:9resolutionKiểu: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
Giá trị:2K4K
Lỗi
- 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.
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ề.
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.
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.
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.
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.
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ùng một endpoint trên Node.js, Python và cURL
Node.js
Workflows API trong Node.js
Gọi workflows API của Photta từ backend Node.js bằng fetch gốc. Không cần SDK: chỉ cần lưu key, gửi job và poll kết quả.
ĐọcPython
Workflows API trong Python
Gọi workflows API của Photta trong Python với thư viện requests. Wrapper ba mươi dòng, hỗ trợ async qua httpx, hoạt động trong Django, FastAPI và Celery.
ĐọccURL
Workflows API với cURL
Gọi trực tiếp workflows API của Photta từ shell bằng cURL. Gửi request, poll, tải về — mọi snippet đều kết hợp hoàn hảo với jq cho các script pipeline.
Đọc
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
Tính năng
Virtual try-on API cho trang phục
REST API giúp mặc trang phục lên mannequin AI. Bất đồng bộ, thời gian tạo 1.5–4 phút, 5 credits ở 2K, 6 ở 4K. Kèm ví dụ cURL, Node.js và Python.
Xem endpointTính năng
API try-on trang sức dành cho dây chuyền, nhẫn, vòng tay và hoa tai
Đưa dây chuyền, nhẫn, vòng tay và hoa tai lên người mẫu AI qua REST. 5 credits ở độ phân giải 2K, tích hợp sẵn mannequin cận cảnh, render chuẩn phản chiếu theo tài liệu Photta.
Xem endpointXây dựng
Xây dựng dịch vụ chụp ảnh sản phẩm bằng AI
Sổ tay chiến lược dành cho founder để bán lại virtual try-on API của Photta dưới dạng SaaS white-label: khóa cho từng tenant, xử lý phân nhánh hàng loạt, thanh toán theo credit, thực tế về SLA.
Xem endpointSo sánh
Photta vs Ayna — API cho lập trình viên hay studio chuyên cho Shopify
So sánh Photta vs Ayna: ba REST endpoint đối đầu với studio ưu tiên Shopify + API. Cả hai đều có thế mạnh riêng. Dữ liệu trích xuất từ website mỗi bên vào 2026-04-19.
Xem endpointBắt đầu nhanh
Tạo ảnh Photta đầu tiên trong vòng chưa đầy năm phút.
Đăng ký, tạo API key, chạy lệnh cURL đầu tiên, polling cho đến khi hoàn thành, lưu trữ kết quả. Năm bước, có tài liệu hướng dẫn trọn gói từ đầu đến cuối.
Xem endpointTài liệu tham khảo
Mã lỗi Photta API
Danh sách đầy đủ các loại lỗi của Photta API kèm theo status code, cấu trúc body của lỗi, và những lỗi nào có thể thử lại.
Xem endpointTài liệu tham khảo
Rate limit của Photta API
Rate limit của Photta API, khung thời gian, header Retry-After, khoảng thời gian polling và giới hạn đồng thời theo từng gói, tất cả đều được lấy từ tài liệu API.
Xem endpoint
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