API reference / Mockups
Save mockup layouts
POST
/api/v1/mockupsParameters
Idempotency-Keyheaderrequiredstring
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
generationIdbodyrequiredstring · uuid
variantIdbodyoptionalstring · uuid
statebodyrequiredobject
fitMotionToDevicebodyoptionalboolean
View complete request schema
{
"$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)$"
},
"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)$"
},
"state": {
"type": "object",
"properties": {
"selectedMediaPath": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 1024
},
{
"type": "null"
}
]
},
"deviceModelId": {
"default": "iphone-17-pro",
"type": "string",
"enum": [
"iphone-17-pro",
"google-pixel-10-pro",
"ipad-pro",
"macbook-pro-14",
"iphone-duo"
]
},
"motion": {
"type": "string",
"enum": [
"hero-reveal",
"feature-sweep",
"showcase-orbit",
"parallax-tilt",
"custom"
]
},
"finish": {
"type": "string",
"enum": [
"silver",
"black",
"glacier",
"burgundy",
"cosmic-orange",
"deep-blue",
"pixel-obsidian",
"pixel-porcelain",
"pixel-moonstone",
"duo-night-sky",
"duo-star-white"
]
},
"speed": {
"type": "number",
"minimum": 0.7,
"maximum": 1.4
},
"background": {
"type": "string",
"enum": [
"soft",
"paper",
"midnight",
"transparent"
]
},
"backgroundMode": {
"default": "color",
"type": "string",
"enum": [
"color",
"gradient",
"image"
]
},
"backgroundColor": {
"type": "string"
},
"backgroundGradient": {
"default": null,
"anyOf": [
{
"type": "object",
"properties": {
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"angle": {
"type": "number"
}
},
"required": [
"from",
"to",
"angle"
],
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"backgroundImage": {
"default": null,
"anyOf": [
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"storagePath": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"blur": {
"type": "number",
"minimum": 0,
"maximum": 20
},
"verticalOffset": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"horizontalOffset": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"attribution": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"pexels",
"unsplash"
]
},
"photographer": {
"type": "string"
},
"photographerUrl": {
"type": "string"
},
"pexelsUrl": {
"type": "string"
},
"unsplashUrl": {
"type": "string"
}
},
"required": [
"source",
"photographer",
"photographerUrl"
],
"additionalProperties": {}
}
},
"required": [
"url"
],
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"showDynamicIsland": {
"default": false,
"type": "boolean"
},
"lidOpen": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"outputRatio": {
"type": "string",
"enum": [
"1:1",
"4:3",
"16:9",
"9:16"
]
},
"motionDuration": {
"type": "number",
"minimum": 1,
"maximum": 60
},
"deviceScale": {
"type": "number",
"minimum": 0.7,
"maximum": 1.3
},
"primaryKeyframes": {
"minItems": 2,
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"time": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"x": {
"type": "number",
"minimum": -3,
"maximum": 3
},
"y": {
"type": "number",
"minimum": -3,
"maximum": 3
},
"rotationX": {
"type": "number",
"minimum": -6.283185307179586,
"maximum": 6.283185307179586
},
"rotationY": {
"type": "number",
"minimum": -6.283185307179586,
"maximum": 6.283185307179586
},
"rotationZ": {
"type": "number",
"minimum": -6.283185307179586,
"maximum": 6.283185307179586
},
"scale": {
"type": "number",
"minimum": 0.2,
"maximum": 3
},
"lidOpen": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"easing": {
"type": "string",
"enum": [
"linear",
"ease-in",
"ease-out",
"ease-in-out"
]
}
},
"required": [
"id",
"time",
"x",
"y",
"rotationX",
"rotationY",
"rotationZ",
"scale",
"easing"
],
"additionalProperties": {}
}
},
"isPlaying": {
"type": "boolean"
},
"overlay": {
"default": null,
"anyOf": [
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"mediaPath": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 1024
},
{
"type": "null"
}
]
},
"shape": {
"type": "string",
"enum": [
"circle",
"rectangle"
]
},
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"size": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"mirrored": {
"type": "boolean"
},
"audioVolume": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"enabled",
"mediaPath",
"shape",
"x",
"y",
"size",
"mirrored"
],
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"audio": {
"default": null,
"anyOf": [
{
"type": "object",
"properties": {
"storagePath": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
]
},
"bundledMusicId": {
"anyOf": [
{
"type": "string",
"enum": [
"clean-tech-pulse",
"optimistic-product-pop",
"cinematic-innovation",
"warm-human-motion",
"luxury-ambient",
"playful-kinetic",
"high-energy-social",
"calm-utility",
"night-drive",
"lofi-daydream",
"sunrise-organic",
"bold-launch"
]
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fileName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sourceDurationSeconds": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
},
"startTimeSeconds": {
"default": 0,
"type": "number",
"minimum": 0
},
"volume": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"volume"
],
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"devices": {
"minItems": 1,
"maxItems": 6,
"type": "array",
"items": {
"type": "object",
"properties": {
"selectedMediaPath": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 1024
},
{
"type": "null"
}
]
},
"deviceModelId": {
"default": "iphone-17-pro",
"type": "string",
"enum": [
"iphone-17-pro",
"google-pixel-10-pro",
"ipad-pro",
"macbook-pro-14",
"iphone-duo"
]
},
"motion": {
"type": "string",
"enum": [
"hero-reveal",
"feature-sweep",
"showcase-orbit",
"parallax-tilt",
"custom"
]
},
"finish": {
"type": "string",
"enum": [
"silver",
"black",
"glacier",
"burgundy",
"cosmic-orange",
"deep-blue",
"pixel-obsidian",
"pixel-porcelain",
"pixel-moonstone",
"duo-night-sky",
"duo-star-white"
]
},
"deviceScale": {
"type": "number",
"minimum": 0.7,
"maximum": 1.3
},
"showDynamicIsland": {
"default": false,
"type": "boolean"
},
"primaryKeyframes": {
"minItems": 2,
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"time": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"x": {
"type": "number",
"minimum": -3,
"maximum": 3
},
"y": {
"type": "number",
"minimum": -3,
"maximum": 3
},
"rotationX": {
"type": "number",
"minimum": -6.283185307179586,
"maximum": 6.283185307179586
},
"rotationY": {
"type": "number",
"minimum": -6.283185307179586,
"maximum": 6.283185307179586
},
"rotationZ": {
"type": "number",
"minimum": -6.283185307179586,
"maximum": 6.283185307179586
},
"scale": {
"type": "number",
"minimum": 0.2,
"maximum": 3
},
"lidOpen": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"easing": {
"type": "string",
"enum": [
"linear",
"ease-in",
"ease-out",
"ease-in-out"
]
}
},
"required": [
"id",
"time",
"x",
"y",
"rotationX",
"rotationY",
"rotationZ",
"scale",
"easing"
],
"additionalProperties": {}
}
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"name": {
"type": "string",
"maxLength": 60
},
"start": {
"type": "number",
"minimum": 0,
"maximum": 59.9
},
"end": {
"anyOf": [
{
"type": "number",
"minimum": 0.1,
"maximum": 60
},
{
"type": "null"
}
]
},
"entrance": {
"type": "string",
"enum": [
"none",
"fade",
"slide",
"scale"
]
},
"exit": {
"type": "string",
"enum": [
"none",
"fade",
"slide",
"scale"
]
},
"transitionDuration": {
"type": "number",
"minimum": 0.1,
"maximum": 3
}
},
"required": [
"selectedMediaPath",
"motion",
"finish",
"deviceScale",
"primaryKeyframes",
"id",
"name",
"start",
"end",
"entrance",
"exit",
"transitionDuration"
],
"additionalProperties": {}
}
}
},
"required": [
"selectedMediaPath",
"motion",
"finish",
"speed",
"background",
"backgroundColor",
"outputRatio",
"motionDuration",
"deviceScale",
"primaryKeyframes",
"isPlaying"
],
"additionalProperties": {}
},
"fitMotionToDevice": {
"type": "boolean"
}
},
"required": [
"generationId",
"state"
],
"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/mockups" \
--header "Authorization: Bearer $ALF_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: $ALF_REQUEST_ID" \
--data '{
"generationId": "11111111-1111-4111-8111-111111111111",
"state": {
"selectedMediaPath": "string",
"motion": "hero-reveal",
"finish": "silver",
"speed": 0.7,
"background": "soft",
"backgroundColor": "string",
"outputRatio": "1:1",
"motionDuration": 1,
"deviceScale": 0.7,
"primaryKeyframes": [
{
"id": "11111111-1111-4111-8111-111111111111",
"time": 0,
"x": -3,
"y": -3,
"rotationX": -6.283185307179586,
"rotationY": -6.283185307179586,
"rotationZ": -6.283185307179586,
"scale": 0.2,
"easing": "linear"
}
],
"isPlaying": true
}
}'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.
projectdatarequiredobject
variantIddataoptionalstring · uuid
ignoredFieldsdataoptionalstring[]
warningsdataoptionalstring[]
View response schema
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"project": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"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)$"
},
"ignoredFields": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"project"
],
"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.