Sign in
Commercial Shorts

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%3Acommerce_shortcut/actions/run/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; once the work ends, that status answer gives you the result files.

    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%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"
      }'
  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

    When it has succeeded, the result files are in the status answer’s artifacts. Call the download_url of the one you want with the same key to get the file.

    curl
    # 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

NameTypeRequiredDescription
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.

Commercial Shorts

Hand it off now