로그인
Commercial Shorts

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%3Acommerce_shortcut/actions/run/uploads" \
      -H "Authorization: Bearer $FLOW_API_KEY" \
      -F "slot=product_images" \
      -F "file=@<file>"
  3. 맡기기

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

    답의 result.run_id로 상태를 보고, 끝나면 그 상태 답에서 결과 파일을 받습니다.

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

    curl
    curl -X POST \
      "$FLOW_URL/v1/agencies/agency%3Acommerce_shortcut/actions/run/runs" \
      -H "Authorization: Bearer $FLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "inputs": {
          "product_images": [<descriptor>, <descriptor>],
          "min_length_seconds": "15",
          "max_length_seconds": "30",
          "language": "ko",
          "captions": "on"
        },
        "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. 결과 받기

    succeeded면 상태 답의 artifacts에 결과 파일이 옵니다. 받을 항목의 download_url을 같은 키로 부르면 파일을 받습니다.

    curl
    # 파일 받기: $FLOW_URL 뒤에 artifacts[]의 download_url
    curl -L "$FLOW_URL<download_url>" \
      -H "Authorization: Bearer $FLOW_API_KEY" \
      -o <filename>

맡길 때 넣는 것run

이름형식필수설명
captions stringenum: "on", "off" 아니요 자막을 켜거나(on) 끕니다(off). 보내지 않으면 켭니다.
language stringenum: "ko", "en", "ja", "zh", "es", "pt", "fr", "de", "vi", "th", "id" 아니요 영상의 언어입니다. 보내지 않으면 한국어(ko)입니다.
logo_images arrayitems: object 아니요 브랜드 로고입니다. slot을 logo_images로 올린 descriptor 하나를 넣습니다.
max_length_seconds stringenum: "5", "10", "15", "20", "25", "30", "35", "40", "45", "50", "55", "60" 예 영상의 가장 긴 길이(초)입니다. 숫자가 아닌 문자열로 보냅니다.
min_length_seconds stringenum: "5", "10", "15", "20", "25", "30", "35", "40", "45", "50", "55", "60" 예 영상의 가장 짧은 길이(초)입니다. 숫자가 아닌 문자열로 보냅니다.
model object 아니요 자동 또는 모델 라이브러리에서 이번 영상에 사용할 모델을 선택합니다. selection_mode auto: 제품과 영상에 맞는 새 인물을 자동으로 만듭니다. 이 인물은 이 영상에만 씁니다. selection_mode load, record_id, revision_id: 내 모델과 팀·조직 공유 모델에서 직접 선택합니다.
product_images arrayitems: object 아니요 제품 사진입니다. 올리기에서 받은 descriptor를 6개까지 넣습니다.
product_source stringenum: "url", "upload" 아니요 제품을 무엇으로 줄지 고릅니다. url이면 product_url만, upload면 product_images만 씁니다. 보내지 않으면 upload입니다.
product_url string 아니요 소개할 제품의 페이지 주소입니다. product_source가 url이면 넣습니다.
project_id stringminLength: 1 예 프로젝트 번호입니다.
reference_source stringenum: "url", "upload" 아니요 참고 영상을 무엇으로 줄지 고릅니다. url이면 reference_url만, upload면 reference_video만 씁니다. 보내지 않으면 url입니다.
reference_url string 아니요 참고 영상 URL. YouTube·Instagram·TikTok, Facebook 릴스·광고 라이브러리 광고, .mp4·.m4v 영상 파일의 공개 URL을 넣을 수 있습니다. 참고 영상은 1분 이하만 쓸 수 있습니다. 영상 내 소리와 배경음악은 별도의 저작권이 있을 수 있습니다. 이에 대한 법적 책임은 Flow가 지지 않습니다.
reference_video arrayitems: object 아니요 참고 영상 파일. slot을 reference_video로 올린 descriptor 하나를 넣습니다. 참고 영상은 1분 이하만 쓸 수 있습니다. 영상 내 소리와 배경음악은 별도의 저작권이 있을 수 있습니다. 이에 대한 법적 책임은 Flow가 지지 않습니다.
request_id stringminLength: 1 예 이 요청의 번호입니다.

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

Commercial Shorts

바로 맡기기