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.
-
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: Bearerheader. The code below reads the key and the address from these two lines.export FLOW_API_KEY="<api_key>" export FLOW_URL="https://flow.unblanq.com" -
Upload photos
Call once for each photo, with
slotset toproduct_images. Keep thedescriptorfrom each answer.It takes PNG, JPEG and WebP, up to 6 photos in one hand-off. An uploaded photo is kept until the
expires_atin itsdescriptor.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>" -
Hand it off
Put the
descriptorof each photo inproduct_imagesand send.idempotency_keyis your own reference for this request.Use
result.run_idfrom the answer to check the status, andresult.admission.target_idto find the result.Send the same
idempotency_keywith the sameinputsagain within 24 hours, and nothing new is handed off: you get the first answer back (deduplicated: true). If theinputsdiffer, it is refused with 409.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" }' -
Check the status
Call it every few seconds until the work ends. It has ended when
statusis one ofsucceeded,failed,cancelled.If it
failed,public_errorssays why.curl "$FLOW_URL/v1/runs/<run_id>" \ -H "Authorization: Bearer $FLOW_API_KEY" -
Get the result
The result is kept as a project. First find, in the list, the
record_idof the item whoserecord_keyis yourtarget_id. If it isn’t on the first page, put the answer’snext_cursorincursorfor the next page.Read with that
record_id, and the result files come back as a list inresult.outputs. Pick therecord_idandrevision_idof the one you want. Never put thetarget_idwhere therecord_idgoes.To download, send the project’s
record_id, and therecord_id(asoutput_record_id) andrevision_idof the file you picked. Call the answer’sresult.download_urlwith the same key to get the file.# 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
| Name | Type | Required | Description |
|---|---|---|---|
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.