ログイン
Packshot Studio

API で任せる

写真をアップロードして任せ、終わったら結果のファイルを受け取ります。

API で任せた仕事も、画面で任せた仕事と同じようにプロジェクトとして残り、同じ残高から差し引かれます。

  1. キーを作る

    ログインしたあと、左のメニューの「API キー」で作ります。キーは、ワークスペースごとに一人一つです。

    すべてのリクエストは、Authorization: Bearer ヘッダーでキーを送ります。以下のコードは、キーと URL をこの2行から読み込みます。

    shell
    export FLOW_API_KEY="<api_key>"
    export FLOW_URL="https://flow.unblanq.com"
  2. 写真をアップロードする

    写真1枚ごとに1回呼び出します。slot は product_images にし、レスポンスの descriptor を集めておきます。

    PNG・JPEG・WebP 形式を、1件につき 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 を選びます。record_id の代わりに target_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. ダウンロード:ファイルの URL は 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 で、必ず1つ以上選びます。
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

今すぐ任せる