기능 · Workflows

Workflows API 한 번의 호출, 하나의 프리셋

한 줄 요약

Photta의 workflows API는 제품 이미지에 기성 씬 템플릿을 적용해 실행합니다. 카탈로그를 조회하고, 워크플로의 이미지 슬롯과 옵션을 채워 POST한 뒤, 반환된 각 항목이 완료될 때까지 폴링하세요.

  • 일반적인 소요 시간: 20–60 sec / image
  • 크레딧: 2K에서 4 크레딧 · 4K에서 5 크레딧
  • 처리 방식: 비동기, 폴링
  • 제한 사항: 600 requests/min
  • 인증: Bearer 키

이 페이지의 모든 수치는 다음 출처를 기반으로 합니다: 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
크레딧
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')

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는 웹훅을 전송하지 않습니다.

카탈로그 조회, 슬롯 채우기, 실행

워크플로 목록 조회, 정의된 슬롯 입력, 제출, 각 항목 폴링, 다운로드.

  1. 단계 1

    API 키 생성

    Workflows는 다른 모든 Photta 기능과 동일한 인증 정보 및 동일한 크레딧 잔액을 사용합니다.

  2. 단계 2

    워크플로 카탈로그 목록 조회

    GET `/api/v1/workflows`는 7개 카테고리에 걸친 53개의 템플릿을 반환하며, 각 템플릿은 자체 이미지 슬롯, 옵션 enum 및 기본 화면비를 정의합니다. `category`로 필터링할 수 있으며, 알 수 없는 카테고리는 무시되지 않고 400을 반환합니다.

  3. 단계 3

    실행 요청 POST

    카탈로그 항목에서 확인한 `images`(슬롯 id와 이미지 매핑) 및 `options`(옵션 id와 선택지 id 매핑)와 함께 POST `/api/v1/workflows/:workflow_id`를 호출하세요. `user_text`에는 자유 형식의 스타일링 요청을 입력할 수 있으며, `num_images`로 한 번의 호출에 1~4장의 이미지를 생성할 수 있습니다.

  4. 단계 4

    모든 항목 폴링

    202 응답에는 요청한 이미지당 하나의 항목이 포함됩니다. `data.status`가 `completed` 또는 `failed`가 될 때까지 각 id에 대해 3초마다 GET `/api/v1/workflows/generations/:id`를 호출하세요. 이미지당 일반적인 완료 시간은 20~60초입니다.

  5. 단계 5

    다운로드 및 저장

    완료된 각 항목에는 자체 `output_url`이 포함됩니다. 항목들은 독립적으로 완료되므로, 나머지가 렌더링되는 동안 첫 번째 항목을 바로 게시할 수 있습니다.

워크플로 실행 전 개발자들이 자주 묻는 질문

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`로 필터링된 페이지네이션 뷰를 제공합니다.

관련 기능

이 페이지의 모든 수치는 다음 출처를 기반으로 합니다: Photta API 문서 · 확인 완료

5분 만에 API 체험하기

Photta API 키를 발급받고 위 cURL 스니펫을 붙여넣기만 하면, 커피가 다 내려지기도 전에 첫 번째 모델 착용 컷을 받아볼 수 있습니다.

  • 20–60 sec / image
  • 2K에서 4 크레딧 · 4K에서 5 크레딧
  • 비동기, 폴링
  • 600 requests/min
  • Bearer 키