API reference / Promo videos

Generate a promo video

POST/api/v1/promovideo/generate

Authorization

Send your API key or MCP OAuth token in the Authorization: Bearer header. Active or trialing Unlimited is required.

Required permission designs:write

Every mutation requires JSON and an Idempotency-Key. Reuse the same key and exact input when retrying.

Parameters

Idempotency-Keyheaderrequired

string

Persist this key for retries. Reusing it with changed input returns 409. Receipts are retained for at least 24 hours.

min length: 8 · max length: 128

Request body

application/json

projectIdbodyrequired

string · uuid

messagebodyoptional

string

max length: 4000

variantIdbodyoptional

string · uuid

selectedScreenshotPathsbodyoptional

string[]

min items: 1 · max items: 10

selectedScreenshotIndicesbodyoptional

integer[]

min items: 1 · max items: 10

deviceTypebodyoptional

"phone" | "tablet" | "desktop"

default: "phone"

replaceVariantIdbodyoptional

string · uuid

candidateCountbodyoptional

View complete request schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "message": {
      "type": "string",
      "maxLength": 4000
    },
    "variantId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "selectedScreenshotPaths": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 512
      }
    },
    "selectedScreenshotIndices": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 49
      }
    },
    "deviceType": {
      "default": "phone",
      "type": "string",
      "enum": [
        "phone",
        "tablet",
        "desktop"
      ]
    },
    "replaceVariantId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "candidateCount": {
      "type": "number",
      "const": 3
    }
  },
  "required": [
    "projectId"
  ],
  "additionalProperties": false
}

Request example

Set ALF_API_URL to https://dashboard.applaunchflow.com/api/v1 and ALF_API_KEY to your key. Replace sample IDs with your project’s values. Use a new ALF_REQUEST_ID for each new operation.

cURL

curl --request POST \
  --url "$ALF_API_URL/promovideo/generate" \
  --header "Authorization: Bearer $ALF_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $ALF_REQUEST_ID" \
  --data '{
  "projectId": "11111111-1111-4111-8111-111111111111"
}'

This example shows the request structure. Some editor operations require additional query parameters that are not yet described in OpenAPI.

Response

Successful JSON responses wrap the result in data, with a request ID in meta.requestId.

generationIddatarequired

string · uuid

candidateKeydatarequired

string

candidatesdatarequired

object[]

screenshotPathsdatarequired

string[]

View response schema

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "generationId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "candidateKey": {
          "type": "string"
        },
        "candidates": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "config": {
                "type": "object",
                "properties": {
                  "scenes": {
                    "maxItems": 100,
                    "type": "array",
                    "items": {
                      "oneOf": [
                        {
                          "type": "object",
                          "properties": {
                            "duration": {
                              "anyOf": [
                                {
                                  "type": "number",
                                  "exclusiveMinimum": 0,
                                  "maximum": 3600
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "hidden": {
                              "type": "boolean"
                            },
                            "type": {
                              "type": "string",
                              "const": "hook"
                            },
                            "content": {
                              "type": "object",
                              "properties": {
                                "appName": {
                                  "anyOf": [
                                    {
                                      "type": "string",
                                      "maxLength": 20000
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "tagline": {
                                  "anyOf": [
                                    {
                                      "type": "string",
                                      "maxLength": 20000
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "additionalProperties": {}
                            }
                          },
                          "required": [
                            "type",
                            "content"
                          ],
                          "additionalProperties": {}
                        },
                        {
                          "type": "object",
                          "properties": {
                            "duration": {
                              "anyOf": [
                                {
                                  "type": "number",
                                  "exclusiveMinimum": 0,
                                  "maximum": 3600
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "hidden": {
                              "type": "boolean"
                            },
                            "type": {
                              "type": "string",
                              "const": "feature"
                            },
                            "content": {
                              "type": "object",
                              "properties": {
                                "screenshotIndex": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "maximum": 99
                                },
                                "title": {
                                  "type": "string",
                                  "maxLength": 20000
                                },
                                "subtitle": {
                                  "anyOf": [
                                    {
                                      "type": "string",
                                      "maxLength": 20000
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "required": [
                                "screenshotIndex",
                                "title"
                              ],
                              "additionalProperties": {}
                            }
                          },
                          "required": [
                            "type",
                            "content"
                          ],
                          "additionalProperties": {}
                        },
                        {
                          "type": "object",
                          "properties": {
                            "duration": {
                              "anyOf": [
                                {
                                  "type": "number",
                                  "exclusiveMinimum": 0,
                                  "maximum": 3600
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "hidden": {
                              "type": "boolean"
                            },
                            "type": {
                              "type": "string",
                              "const": "text-only"
                            },
                            "content": {
                              "type": "object",
                              "properties": {
                                "headline": {
                                  "type": "string",
                                  "maxLength": 20000
                                },
                                "subheadline": {
                                  "anyOf": [
                                    {
                                      "type": "string",
                                      "maxLength": 20000
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "required": [
                                "headline"
                              ],
                              "additionalProperties": {}
                            }
                          },
                          "required": [
                            "type",
                            "content"
                          ],
                          "additionalProperties": {}
                        },
                        {
                          "type": "object",
                          "properties": {
                            "duration": {
                              "anyOf": [
                                {
                                  "type": "number",
                                  "exclusiveMinimum": 0,
                                  "maximum": 3600
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "hidden": {
                              "type": "boolean"
                            },
                            "type": {
                              "type": "string",
                              "const": "closeup"
                            },
                            "content": {
                              "type": "object",
                              "properties": {
                                "screenshotIndex": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "maximum": 99
                                },
                                "caption": {
                                  "anyOf": [
                                    {
                                      "type": "string",
                                      "maxLength": 20000
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "focusRegion": {
                                  "anyOf": [
                                    {
                                      "type": "object",
                                      "properties": {
                                        "x": {
                                          "type": "number"
                                        },
                                        "y": {
                                          "type": "number"
                                        },
                                        "width": {
                                          "type": "number",
                                          "exclusiveMinimum": 0
                                        },
                                        "height": {
                                          "type": "number",
                                          "exclusiveMinimum": 0
                                        }
                                      },
                                      "required": [
                                        "x",
                                        "y",
                                        "width",
                                        "height"
                                      ]
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "required": [
                                "screenshotIndex"
                              ],
                              "additionalProperties": {}
                            }
                          },
                          "required": [
                            "type",
                            "content"
                          ],
                          "additionalProperties": {}
                        },
                        {
                          "type": "object",
                          "properties": {
                            "duration": {
                              "anyOf": [
                                {
                                  "type": "number",
                                  "exclusiveMinimum": 0,
                                  "maximum": 3600
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "hidden": {
                              "type": "boolean"
                            },
                            "type": {
                              "type": "string",
                              "const": "multi-phone"
                            },
                            "content": {
                              "type": "object",
                              "properties": {
                                "screenshotIndexes": {
                                  "minItems": 1,
                                  "maxItems": 6,
                                  "type": "array",
                                  "items": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "maximum": 99
                                  }
                                },
                                "title": {
                                  "anyOf": [
                                    {
                                      "type": "string",
                                      "maxLength": 20000
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "layout": {
                                  "type": "string",
                                  "enum": [
                                    "cascade",
                                    "fan",
                                    "side-by-side",
                                    "custom"
                                  ]
                                }
                              },
                              "required": [
                                "screenshotIndexes",
                                "layout"
                              ],
                              "additionalProperties": {}
                            }
                          },
                          "required": [
                            "type",
                            "content"
                          ],
                          "additionalProperties": {}
                        },
                        {
                          "type": "object",
                          "properties": {
                            "duration": {
                              "anyOf": [
                                {
                                  "type": "number",
                                  "exclusiveMinimum": 0,
                                  "maximum": 3600
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "hidden": {
                              "type": "boolean"
                            },
                            "type": {
                              "type": "string",
                              "const": "cta"
                            },
                            "content": {
                              "type": "object",
                              "properties": {
                                "appName": {
                                  "anyOf": [
                                    {
                                      "type": "string",
                                      "maxLength": 20000
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "downloadText": {
                                  "anyOf": [
                                    {
                                      "type": "string",
                                      "maxLength": 20000
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "badge": {
                                  "anyOf": [
                                    {
                                      "type": "string",
                                      "enum": [
                                        "appStore",
                                        "googlePlay",
                                        "both",
                                        "none"
                                      ]
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "additionalProperties": {}
                            }
                          },
                          "required": [
                            "type",
                            "content"
                          ],
                          "additionalProperties": {}
                        }
                      ]
                    }
                  },
                  "theme": {
                    "type": "object",
                    "properties": {
                      "colors": {
                        "type": "object",
                        "propertyNames": {
                          "type": "string"
                        },
                        "additionalProperties": {
                          "type": "string"
                        }
                      },
                      "typography": {
                        "type": "object",
                        "properties": {
                          "fontFamily": {
                            "type": "string"
                          },
                          "titleSize": {
                            "type": "number",
                            "exclusiveMinimum": 0
                          },
                          "subtitleSize": {
                            "type": "number",
                            "exclusiveMinimum": 0
                          }
                        },
                        "additionalProperties": {}
                      }
                    },
                    "additionalProperties": {}
                  }
                },
                "required": [
                  "scenes"
                ],
                "additionalProperties": {}
              }
            },
            "required": [
              "config"
            ],
            "additionalProperties": {}
          }
        },
        "screenshotPaths": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "generationId",
        "candidateKey",
        "candidates",
        "screenshotPaths"
      ],
      "additionalProperties": {}
    },
    "meta": {
      "type": "object",
      "required": [
        "requestId"
      ],
      "properties": {
        "requestId": {
          "type": "string",
          "format": "uuid"
        }
      }
    }
  }
}

Errors & retries

Errors use application/problem+json. Check the stable code and keep requestId when contacting support. Respect Retry-After on 429 responses.

See error handling and idempotency →