로그인
Packshot Studio

API로 맡기기

사진을 올리고, 맡기고, 끝나면 결과 파일을 받습니다.

API로 맡긴 일도 화면에서 맡긴 일처럼 프로젝트로 남고, 같은 잔액에서 빠집니다.

  1. 키 만들기

    로그인한 뒤 왼쪽 메뉴의 「API 키」에서 만듭니다. 키는 작업 공간마다 한 사람에 하나입니다.

    모든 요청은 Authorization: Bearer 머리글에 키를 담습니다. 아래 코드는 키와 주소를 이 두 줄에서 읽습니다.

    shell
    export FLOW_API_KEY="<api_key>"
    export FLOW_URL="https://flow.unblanq.com"
  2. 사진 올리기

    사진 한 장마다 한 번 부릅니다. slot은 product_images이고, 답의 descriptor를 모아 둡니다.

    PNG·JPEG·WebP 형식을 한 건에 6장까지 받습니다. 올린 사진은 descriptor의 expires_at까지 보관됩니다.

    curl
    curl -X POST \
      "$FLOW_URL/v1/agencies/agency%3Aproduct_cut_studio/actions/generate_product_cuts/uploads" \
      -H "Authorization: Bearer $FLOW_API_KEY" \
      -F "slot=product_images" \
      -F "file=@<file>"
  3. 맡기기

    모아 둔 descriptor를 product_images에 넣어 보냅니다. idempotency_key는 내가 정해 이 요청에 붙이는 번호입니다.

    답의 result.run_id로 상태를 보고, result.admission.target_id로 결과를 찾습니다.

    같은 idempotency_key와 같은 inputs로 24시간 안에 다시 보내면 새로 맡기지 않고, 처음 맡긴 일의 답을 다시 줍니다(deduplicated: true). inputs가 다르면 409로 거절합니다.

    curl
    curl -X POST \
      "$FLOW_URL/v1/agencies/agency%3Aproduct_cut_studio/actions/generate_product_cuts/runs" \
      -H "Authorization: Bearer $FLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "inputs": {
          "operation": "create",
          "product_images": [<descriptor>, <descriptor>],
          "cut_types": ["flat_lay", "hanger"]
        },
        "idempotency_key": "request-001"
      }'
  4. 상태 보기

    끝날 때까지 몇 초마다 부릅니다. status가 succeeded·failed·cancelled 가운데 하나가 되면 끝난 것입니다.

    failed면 public_errors에 까닭이 옵니다.

    curl
    curl "$FLOW_URL/v1/runs/<run_id>" \
      -H "Authorization: Bearer $FLOW_API_KEY"
  5. 결과 받기

    결과는 프로젝트로 남습니다. 먼저 목록에서 record_key가 target_id인 항목의 record_id를 찾습니다. 첫 쪽에 없으면 답의 next_cursor를 cursor에 넣어 다음 쪽을 봅니다.

    그 record_id로 읽으면 결과 파일 목록이 result.outputs로 옵니다. 받을 파일의 record_id와 revision_id를 고릅니다. target_id를 record_id 자리에 넣지 않습니다.

    내려받기에는 프로젝트의 record_id, 고른 파일의 record_id(output_record_id)와 revision_id를 넣습니다. 답의 result.download_url을 같은 키로 부르면 파일을 받습니다.

    curl
    # 1. 목록: record_key가 target_id인 항목의 record_id
    curl -X POST \
      "$FLOW_URL/v1/agencies/agency%3Aproduct_cut_studio/actions/list_product_cut_projects/runs" \
      -H "Authorization: Bearer $FLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"inputs": {"relation": "owned", "limit": 50}}'
    
    # 2. 읽기: 결과 파일 목록은 result.outputs
    curl -X POST \
      "$FLOW_URL/v1/agencies/agency%3Aproduct_cut_studio/actions/read_product_cut_project/runs" \
      -H "Authorization: Bearer $FLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"inputs": {"record_id": "<record_id>"}}'
    
    # 3. 내려받기: 파일의 주소는 result.download_url
    curl -X POST \
      "$FLOW_URL/v1/agencies/agency%3Aproduct_cut_studio/actions/download_product_cut_version/runs" \
      -H "Authorization: Bearer $FLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "inputs": {
          "record_id": "<record_id>",
          "output_record_id": "<output_record_id>",
          "revision_id": "<revision_id>",
          "output_format": "png"
        }
      }'
    
    # 4. 파일 받기: $FLOW_URL 뒤에 download_url
    curl -L "$FLOW_URL<download_url>" \
      -H "Authorization: Bearer $FLOW_API_KEY" \
      -o <filename>

맡길 때 넣는 것generate_product_cuts

이름형식필수설명
cut_types arrayminItems: 1 · items: string · items.enum: "flat_lay", "hanger" 아니요 만들 컷입니다. 바닥 컷은 flat_lay, 행거 컷은 hanger이고, 하나 이상 꼭 고릅니다.
flat_lay object 아니요 바닥 컷의 배경 예시입니다. slot을 flat_lay_reference_image로 올린 descriptor를 reference_image에 넣습니다.
hanger object 아니요 행거 컷의 배경 예시입니다. slot을 hanger_reference_image로 올린 descriptor를 reference_image에 넣습니다.
operation stringenum: "create", "retry_all" 아니요 새 프로젝트는 create를 꼭 보냅니다. 그래야 Flow가 idempotency_key로 project_id를 채웁니다.
output object 아니요 해상도(resolution_tier)와 비율(aspect_ratio)입니다. 보내지 않으면 1k, auto입니다.
product_images arrayminItems: 1 · maxItems: 6 · items: object 아니요 같은 상품을 찍은 사진입니다. 올리기에서 받은 descriptor를 꼭 넣습니다.
product_title stringmaxLength: 320 아니요 상품 이름입니다. 넣지 않아도 됩니다.
project_id string 아니요 프로젝트 번호입니다.
record_id string 아니요 operation이 retry_all일 때 다시 만들 프로젝트의 record_id입니다. 새 프로젝트에는 넣지 않습니다.
request_id stringminLength: 1 예 이 요청의 번호입니다.
schema_version string 아니요 입력 형식의 판입니다. 보내지 않아도 됩니다.
surface_output_mode stringenum: "all_detected", "front_only_when_both" 아니요 앞뒷면이 모두 보일 때 두 면을 만들지(all_detected, 기본), 앞면만 만들지(front_only_when_both)입니다.

project_id와 request_id는 보내지 않아도 됩니다. Flow가 idempotency_key로 채웁니다.

Packshot Studio

바로 맡기기