Sign in
Packshot Studio

Hand it off through the API

Upload the photos, hand off the work, and get the result files when it’s done.

Work handed off through the API is kept as a project, as it is on screen, and comes off the same balance.

  1. Create a key

    Sign in and create one under “API keys” in the left menu. Each person has one key per workspace.

    Every request carries the key in an Authorization: Bearer header. The code below reads the key and the address from these two lines.

    shell
    export FLOW_API_KEY="<api_key>"
    export FLOW_URL="https://flow.unblanq.com"
  2. Upload photos

    Call once for each photo, with slot set to product_images. Keep the descriptor from each answer.

    It takes PNG, JPEG and WebP, up to 6 photos in one hand-off. An uploaded photo is kept until the expires_at in its descriptor.

    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. Hand it off

    Put the descriptor of each photo in product_images and send. idempotency_key is your own reference for this request.

    Use result.run_id from the answer to check the status, and result.admission.target_id to find the result.

    Send the same idempotency_key with the same inputs again within 24 hours, and nothing new is handed off: you get the first answer back (deduplicated: true). If the inputs differ, it is refused with 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. Check the status

    Call it every few seconds until the work ends. It has ended when status is one of succeeded, failed, cancelled.

    If it failed, public_errors says why.

    curl
    curl "$FLOW_URL/v1/runs/<run_id>" \
      -H "Authorization: Bearer $FLOW_API_KEY"
  5. Get the result

    The result is kept as a project. First find, in the list, the record_id of the item whose record_key is your target_id. If it isn’t on the first page, put the answer’s next_cursor in cursor for the next page.

    Read with that record_id, and the result files come back as a list in result.outputs. Pick the record_id and revision_id of the one you want. Never put the target_id where the record_id goes.

    To download, send the project’s record_id, and the record_id (as output_record_id) and revision_id of the file you picked. Call the answer’s result.download_url with the same key to get the file.

    curl
    # 1. List: the record_id of the item whose record_key is your target_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. Read: the result files are listed in 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. Download: the file’s address is in 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. Get the file: download_url goes after $FLOW_URL
    curl -L "$FLOW_URL<download_url>" \
      -H "Authorization: Bearer $FLOW_API_KEY" \
      -o <filename>

What you sendgenerate_product_cuts

NameTypeRequiredDescription
cut_types arrayminItems: 1 · items: string · items.enum: "flat_lay", "hanger" No The cuts to make: flat_lay for flat-lay cuts and hanger for hanger cuts. Always choose at least one.
flat_lay object No A background example for flat-lay cuts. Put the descriptor from an upload with slot set to flat_lay_reference_image in reference_image.
hanger object No A background example for hanger cuts. Put the descriptor from an upload with slot set to hanger_reference_image in reference_image.
operation stringenum: "create", "retry_all" No For a new project, always send create. That is what lets Flow fill in project_id from idempotency_key.
output object No The resolution (resolution_tier) and aspect ratio (aspect_ratio). If you don’t send it, they’re 1k and auto.
product_images arrayminItems: 1 · maxItems: 6 · items: object No Photos of the same product. Always put in the descriptor from each upload.
product_title stringmaxLength: 320 No The product name. It’s optional.
project_id string No The project’s reference.
record_id string No The record_id of the project to remake when operation is retry_all. Leave it out for a new project.
request_id stringminLength: 1 Yes This request’s reference.
schema_version string No The version of the input format. You don’t need to send it.
surface_output_mode stringenum: "all_detected", "front_only_when_both" No When both the front and back are visible, whether to make both sides (all_detected, the default) or the front only (front_only_when_both).

You don’t need to send project_id or request_id: Flow fills them in from idempotency_key.

Packshot Studio

Hand it off now