기능 · Workflows
Workflows API 한 번의 호출, 하나의 프리셋
한 줄 요약
Photta의 workflows API는 제품 이미지에 기성 씬 템플릿을 적용해 실행합니다. 카탈로그를 조회하고, 워크플로의 이미지 슬롯과 옵션을 채워 POST한 뒤, 반환된 각 항목이 완료될 때까지 폴링하세요.
- 일반적인 소요 시간: 20–60 sec / image
- 크레딧: 2K에서 4 크레딧 · 4K에서 5 크레딧
- 처리 방식: 비동기, 폴링
- 제한 사항: 600 requests/min
- 인증: Bearer 키
이 페이지의 모든 수치는 다음 출처를 기반으로 합니다: 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
- 크레딧
- 2K에서 4 크레딧 · 4K에서 5 크레딧
- 화면비
- 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는 웹훅을 전송하지 않습니다.
카탈로그 조회, 슬롯 채우기, 실행
워크플로 목록 조회, 정의된 슬롯 입력, 제출, 각 항목 폴링, 다운로드.
단계 1
API 키 생성
Workflows는 다른 모든 Photta 기능과 동일한 인증 정보 및 동일한 크레딧 잔액을 사용합니다.
단계 2
워크플로 카탈로그 목록 조회
GET `/api/v1/workflows`는 7개 카테고리에 걸친 53개의 템플릿을 반환하며, 각 템플릿은 자체 이미지 슬롯, 옵션 enum 및 기본 화면비를 정의합니다. `category`로 필터링할 수 있으며, 알 수 없는 카테고리는 무시되지 않고 400을 반환합니다.
단계 3
실행 요청 POST
카탈로그 항목에서 확인한 `images`(슬롯 id와 이미지 매핑) 및 `options`(옵션 id와 선택지 id 매핑)와 함께 POST `/api/v1/workflows/:workflow_id`를 호출하세요. `user_text`에는 자유 형식의 스타일링 요청을 입력할 수 있으며, `num_images`로 한 번의 호출에 1~4장의 이미지를 생성할 수 있습니다.
단계 4
모든 항목 폴링
202 응답에는 요청한 이미지당 하나의 항목이 포함됩니다. `data.status`가 `completed` 또는 `failed`가 될 때까지 각 id에 대해 3초마다 GET `/api/v1/workflows/generations/:id`를 호출하세요. 이미지당 일반적인 완료 시간은 20~60초입니다.
단계 5
다운로드 및 저장
완료된 각 항목에는 자체 `output_url`이 포함됩니다. 항목들은 독립적으로 완료되므로, 나머지가 렌더링되는 동안 첫 번째 항목을 바로 게시할 수 있습니다.
Node.js, Python, cURL에서의 동일한 엔드포인트
Node.js
Node.js 환경의 Workflows API
네이티브 fetch를 사용하여 Node.js 백엔드에서 Photta의 workflows API 기능을 호출하세요. SDK는 필요 없습니다: 키를 저장하고 작업을 제출한 뒤 결과를 폴링하면 됩니다.
읽기Python
Python 환경의 Workflows API
requests 라이브러리를 사용하여 Python에서 Photta의 workflows API를 호출하세요. 30줄짜리 래퍼이자 httpx를 통한 비동기 지원이 가능하며, Django, FastAPI, Celery에서 원활하게 동작합니다.
읽기cURL
cURL 기반 Workflows API
cURL을 사용해 셸에서 Photta의 workflows API 기능을 직접 호출하세요. 제출, polling, 다운로드까지 — 모든 스니펫은 스크립트 파이프라인 구축을 위해 jq와 연동됩니다.
읽기
워크플로 실행 전 개발자들이 자주 묻는 질문
workflows API란 무엇인가요?
자체 제품 사진에 적용할 수 있는 기성 씬 템플릿 카탈로그입니다. 프롬프트를 직접 조합하는 대신, 워크플로를 선택하고 해당 워크플로가 정의하는 이미지 슬롯과 옵션을 채우기만 하면 됩니다.
워크플로 1회 실행 비용은 얼마인가요?
이미지당 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 데이터 URI 형태의 이미지 배열에 매핑합니다. `options`는 옵션 id를 해당 옵션의 선택지 id 중 하나에 매핑합니다. 두 규격 모두 카탈로그에서 제공되므로 새 워크플로가 추가되어도 기존 연동 코드를 그대로 유지할 수 있습니다.
한 번의 실행으로 몇 장의 이미지를 생성할 수 있나요?
`num_images`는 1에서 4까지 지정할 수 있습니다. 각 이미지는 독립적으로 생성되며 응답에서 고유한 항목 id를 부여받으므로, 하나가 실패해도 다른 이미지 생성에는 영향을 주지 않습니다.
결과는 어떻게 폴링하나요?
각 항목을 개별적으로 폴링: 3초마다 GET `/api/v1/workflows/generations/:id`를 호출합니다. GET `/api/v1/workflows/generations/list`는 `workflow_id` 또는 `status`로 필터링된 페이지네이션 뷰를 제공합니다.
관련 기능
기능
가상 착용(Virtual try-on) API 의류용
의류를 AI 마네킹에 착용시키는 REST API입니다. 비동기식 처리, 1.5~4분의 생성 시간, 2K 기준 5 credits, 4K 기준 6 credits 소요. cURL, Node.js, Python 예제가 제공됩니다.
엔드포인트 보기기능
주얼리 try-on API 목걸이, 반지, 팔찌 및 귀걸이 지원
REST 방식으로 AI 모델에 목걸이, 반지, 팔찌, 귀걸이를 착용해 보세요. 2K 기준 5 credits, 내장 클로즈업 마네킹 제공, 반사광을 정밀하게 반영하는 Photta 공식 렌더링 파이프라인을 활용하세요.
엔드포인트 보기빌드
AI 제품 사진 촬영 서비스 구축하기
Photta의 가상 try-on API를 화이트라벨 SaaS로 재판매하기 위한 창업자 플레이북: 테넌트 키, 배치 fanout, credit별 결제, 현실적인 SLA.
엔드포인트 보기비교
Photta vs Ayna — 개발자 API 또는 Shopify 우선 스튜디오
Photta vs Ayna 비교: 3개의 REST endpoint와 Shopify 중심 스튜디오 + API의 대결. 둘 다 장점이 있습니다. 2026-04-19에 각 사이트에서 수집한 데이터 기준입니다.
엔드포인트 보기빠른 시작
5분 안에 첫 번째 Photta 이미지를 생성하세요.
회원가입, API 키 생성, 첫 cURL 호출 실행, 완료될 때까지 폴링, 결과 저장까지. 엔드투엔드로 문서화된 5단계 가이드입니다.
엔드포인트 보기레퍼런스
Photta API 오류
Photta API의 전체 오류 유형 목록과 상태 코드, 오류 본문 포맷, 그리고 재시도할 가치가 있는 오류에 대한 안내입니다.
엔드포인트 보기레퍼런스
Photta API rate limits
Photta API rate limit, 윈도우, Retry-After 헤더, polling 주기, 플랜별 동시성 상한선 등 API 문서에 명시된 모든 내용입니다.
엔드포인트 보기
이 페이지의 모든 수치는 다음 출처를 기반으로 합니다: Photta API 문서 · 확인 완료
5분 만에 API 체험하기
Photta API 키를 발급받고 위 cURL 스니펫을 붙여넣기만 하면, 커피가 다 내려지기도 전에 첫 번째 모델 착용 컷을 받아볼 수 있습니다.
- 20–60 sec / image
- 2K에서 4 크레딧 · 4K에서 5 크레딧
- 비동기, 폴링
- 600 requests/min
- Bearer 키