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%3Acommerce_shortcut/actions/run/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; once the work ends, that status answer gives you the result files.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%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": "en", "captions": "on" }, "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
When it has
succeeded, the result files are in the status answer’sartifacts. Call thedownload_urlof the one you want with the same key to get the file.# Get the file: an artifacts[] item’s download_url goes after $FLOW_URL curl -L "$FLOW_URL<download_url>" \ -H "Authorization: Bearer $FLOW_API_KEY" \ -o <filename>
What you sendrun
| Name | Type | Required | Description |
|---|---|---|---|
captions |
stringenum: "on", "off" |
No | Turns captions on (on) or off (off). If you don’t send it, they’re on. |
language |
stringenum: "ko", "en", "ja", "zh", "es", "pt", "fr", "de", "vi", "th", "id" |
No | The language of the video. If you don’t send it, it’s Korean (ko). |
logo_images |
arrayitems: object |
No | The brand logo. Put in one descriptor from an upload with slot set to logo_images. |
max_length_seconds |
stringenum: "5", "10", "15", "20", "25", "30", "35", "40", "45", "50", "55", "60" |
Yes | The longest length of the video, in seconds. Send it as a string, not a number. |
min_length_seconds |
stringenum: "5", "10", "15", "20", "25", "30", "35", "40", "45", "50", "55", "60" |
Yes | The shortest length of the video, in seconds. Send it as a string, not a number. |
model |
object |
No | Choose the model for this video: Auto, or one from the Model Library. selection_mode auto: Automatically creates a new person who fits the product and the video. This person is used for this video only. selection_mode load, record_id, revision_id: Pick one yourself from your models and those shared with your team or organization. |
product_images |
arrayitems: object |
No | Product photos. Put in the descriptor from each upload, up to 6. |
product_source |
stringenum: "url", "upload" |
No | Chooses how you give the product. With url, only product_url is used; with upload, only product_images. If you don’t send it, it’s upload. |
product_url |
string |
No | The URL of the product page to feature. Send it when product_source is url. |
project_id |
stringminLength: 1 |
Yes | The project’s reference. |
reference_source |
stringenum: "url", "upload" |
No | Chooses how you give the reference video. With url, only reference_url is used; with upload, only reference_video. If you don’t send it, it’s url. |
reference_url |
string |
No | Reference video URL. You can enter a public URL from YouTube, Instagram, TikTok, Facebook Reels or Ad Library ads, or of an .mp4 or .m4v video file. Only reference videos of 1 minute or shorter can be used. Sound and background music in the video may be separately copyrighted. Flow takes no legal responsibility for them. |
reference_video |
arrayitems: object |
No | Reference video file. Put in one descriptor from an upload with slot set to reference_video. Only reference videos of 1 minute or shorter can be used. Sound and background music in the video may be separately copyrighted. Flow takes no legal responsibility for them. |
request_id |
stringminLength: 1 |
Yes | This request’s reference. |
You don’t need to send project_id or request_id: Flow fills them in from idempotency_key.