MotionMockups AI API

Submit a MotionMockups AI Request

post

Queue a video generation request for the provided image and return a request_id to poll.

Provide your own prompt for full control, or omit it to let the API generate a prompt from the image (set skip_discovery: true to skip auto-prompting and use a neutral default instead). Allowed duration and aspect_ratio values depend on the selected model — see GET /motion-mockups/models.

Authorizations

apiKeyAuth

x-api-keystringRequired

API key required for authentication.

Header parameters

Acceptstring · enumRequired

The request must accept JSON responses.

Possible values:

x-api-keystringRequired

API key required for authentication.

Example: YOUR_API_KEY_HERE

Body

application/json

start_image_urlstring · uri · max: 2000Required

Publicly accessible URL of the source image to animate.

Example: https://app-dynamicmockups-production.s3.eu-central-1.amazonaws.com/static/api_sandbox_icon.png

modelstring · enumOptional

The MotionMockups AI model to use. Defaults to the standard model when omitted.

Example: kling_v2.6Possible values:

promptstring · max: 2500Optional

Optional text prompt describing the desired video. When omitted, a prompt is generated from the image.

negative_promptstring · max: 1000Optional

Optional description of what to avoid in the generated video.

durationintegerOptional

Video length in seconds. Allowed values depend on the selected model (see GET /motion-mockups/models). Defaults to the model's default duration.

Example: 5

aspect_ratiostringOptional

Output aspect ratio. Only supported by some models, with a model-specific set of allowed values (see GET /motion-mockups/models).

Example: 16:9

generate_audiobooleanOptional

Whether to also generate audio. Increases the credit cost by a model-specific multiplier.

Example: false

skip_discoverybooleanOptional

When true and no prompt is provided, skip image auto-prompting and use a neutral default prompt.

Example: false

Responses

200

Request successfully queued.

application/json

successbooleanOptionalExample: true

messagestringOptionalExample: Image-to-video request submitted successfully

400

Bad request due to invalid input parameters.

401

Unauthorized request, invalid or missing API key.

403

Insufficient credits, or no active workspace for the API key.

422

Validation failed.

500

Failed to submit the request to the generation service.

post/motion-mockups/submit

HTTPcURLJavaScriptPython

POST /api/v1/motion-mockups/submit HTTP/1.1
Host: app.dynamicmockups.com
x-api-key: text
Accept: application/json
Content-Type: application/json
Content-Length: 56

{
  "start_image_url": "https://example.com/my-product.png"
}

Auto-prompt from the imageCustom prompt with audio

{
  "data": {
    "request_id": "7b1f5c2a-3d4e-4f6a-9b8c-1d2e3f4a5b6c",
    "status": "IN_QUEUE",
    "model": "kling_v2.6",
    "credits": 40,
    "status_url": "https://app.dynamicmockups.com/api/v1/motion-mockups/status/7b1f5c2a-3d4e-4f6a-9b8c-1d2e3f4a5b6c"
  },
  "success": true,
  "message": "Image-to-video request submitted successfully"
}

Get MotionMockups AI Request Status

get

Return the current status of a previously submitted request. While generation is in progress status is IN_QUEUE or PROCESSING. On success status is COMPLETED and the response includes a video object with a permanent URL. Terminal failures report FAILED, CANCELLED or ERROR and any reserved credits are refunded automatically.

Authorizations

apiKeyAuth

x-api-keystringRequired

API key required for authentication.

Path parameters

requestIdstringRequired

The request_id returned by the submit endpoint.

Example: 7b1f5c2a-3d4e-4f6a-9b8c-1d2e3f4a5b6c

Header parameters

Acceptstring · enumRequired

The request must accept JSON responses.

Possible values:

x-api-keystringRequired

API key required for authentication.

Example: YOUR_API_KEY_HERE

Responses

200

Current status of the request.

application/json

successbooleanOptionalExample: true

messagestringOptionalExample: Video generation completed

401

Unauthorized request, invalid or missing API key.

403

No active workspace for the API key.

404

No request with that request_id exists for this workspace.

500

Failed to retrieve the request status or result.

get/motion-mockups/status/{requestId}

HTTPcURLJavaScriptPython

GET /api/v1/motion-mockups/status/{requestId} HTTP/1.1
Host: app.dynamicmockups.com
x-api-key: text
Accept: application/json

{
  "data": {
    "request_id": "7b1f5c2a-3d4e-4f6a-9b8c-1d2e3f4a5b6c",
    "status": "COMPLETED",
    "queue_position": 2,
    "video": {
      "url": "https://app-dynamicmockups-production.s3.eu-central-1.amazonaws.com/image-to-video-ai/output.mp4",
      "content_type": "video/mp4",
      "file_name": "output.mp4",
      "file_size": 1048576
    }
  },
  "success": true,
  "message": "Video generation completed"
}

List MotionMockups AI Models

get

List the available models with their allowed durations, per-duration credit costs (with and without audio), estimated generation time and supported aspect ratios.

Authorizations

apiKeyAuth

x-api-keystringRequired

API key required for authentication.

Header parameters

Acceptstring · enumRequired

The request must accept JSON responses.

Possible values:

x-api-keystringRequired

API key required for authentication.

Example: YOUR_API_KEY_HERE

Responses

200

Available models.

application/json

successbooleanOptionalExample: true

messagestringOptionalExample: Available image-to-video models

401

Unauthorized request, invalid or missing API key.

get/motion-mockups/models

HTTPcURLJavaScriptPython

GET /api/v1/motion-mockups/models HTTP/1.1
Host: app.dynamicmockups.com
x-api-key: text
Accept: application/json

{
  "data": {
    "models": [
      {
        "value": "kling_v2.6",
        "display_name": "Kling v2.6",
        "default_duration": "5",
        "durations": [
          {
            "seconds": 5,
            "credits": {
              "audio_off": 40,
              "audio_on": 80
            },
            "estimated_time_minutes": 3
          }
        ],
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "default_aspect_ratio": "16:9",
        "supports_aspect_ratio": true
      }
    ],
    "default_model": "kling_v2.6"
  },
  "success": true,
  "message": "Available image-to-video models"
}

Overview

MotionMockups AI is a standalone image-to-video endpoint - it doesn't need a mockup template or a product. Submit any publicly reachable image URL, and it returns a generated MP4.

Workflow

1. (Optional) Call List MotionMockups AI Models to see the available models, their valid durations, the credit cost of each, and which ones support an aspect ratio.

2. Call Create MotionMockups AI Video with your start_image_url (and optionally a model, duration, or prompt). You get back a request_id.

3. Poll Get MotionMockups AI Video Status with that request_id until status is COMPLETED, then use the returned video.url.

Writing the prompt (or letting our AI decide)

A prompt is optional. Omit it and MotionMockups AI analyzes your image and writes one for you automatically - the fastest way to a good result.

Pass your own prompt when you want to direct the motion (e.g., "slow cinematic push-in with soft studio lighting"), and use negative_prompt to describe what to avoid.

Polling for completion

Generation is asynchronous and usually takes between 2 and 15 minutes, depending on the model and duration (see estimated_time_minutes from the models endpoint). Poll the status endpoint every ~5 seconds.

While the job runs, status is IN_QUEUE or PROCESSING; when it finishes, status is COMPLETED and the response includes a video object.

Using your video

On COMPLETED, the video object contains a url plus content_type, file_name, and file_size. Download it or embed it directly - it's a standard MP4.

Start image URL requirements

start_image_url must be a publicly reachable URL. We recommend clear, well-lit product shots to get the best results.

Duration, aspect ratio, and audio

duration is the length in seconds and must be one of the selected model's allowed values. aspect_ratio is only available on models where supports_aspect_ratio is true - omit it otherwise.

Set generate_audio to true to add a generated soundtrack; Omit any of these, and the model's defaults apply.

Choosing a model

Two models are available. Use the models endpoint for the authoritative, up-to-date list of durations and prices.

Model	Durations	Aspect ratio	Audio	Best for
kling_v2.6 (Kling v2.6 Pro)	5s, 10s	Follows start_image_url ratio (not configurable)	Optional (≈2× credits)	Quick, lower-cost clips
kling_v3_pro (Kling V3 Pro)	3 - 15s	16:9, 9:16, 1:1	Optional (≈1.5× credits)	Longer clips, framing control, higher fidelity

The default model is kling_v2.6.

Credits cost

Each request costs credits based on the model, the duration, and whether audio is enabled. For example, Kling v2.6 Pro is 40 credits for a 5-second clip (80 with audio); Kling V3 Pro is 130 credits for 5 seconds (195 with audio).

You only pay for videos that are generated successfully.

Rate Limit

The submit endpoint is limited to 10 requests per minute; the status and models endpoints are higher, so you can poll freely. Exceeding a limit returns 429. Contact support if you need a higher cap.