> For the complete documentation index, see [llms.txt](https://docs.dynamicmockups.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dynamicmockups.com/api-reference/motionmockups-ai-api.md).
# MotionMockups AI API
## Submit a MotionMockups AI Request
> 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\`.
```json
{"openapi":"3.1.0","info":{"title":"Dynamic Mockups MotionMockups AI API","version":"1.0"},"servers":[{"url":"https://app.dynamicmockups.com/api/v1"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key required for authentication."}}},"paths":{"/motion-mockups/submit":{"post":{"summary":"Submit a MotionMockups AI Request","description":"Queue a video generation request for the provided image and return a `request_id` to poll.\n\nProvide 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`.\n","operationId":"submitMotionMockup","parameters":[{"in":"header","name":"Accept","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"The request must accept JSON responses."},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"API key required for authentication."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"start_image_url":{"type":"string","format":"uri","maxLength":2000,"description":"Publicly accessible URL of the source image to animate."},"model":{"type":"string","description":"The MotionMockups AI model to use. Defaults to the standard model when omitted.","enum":["kling_v2.6","kling_v3_pro"]},"prompt":{"type":"string","maxLength":2500,"description":"Optional text prompt describing the desired video. When omitted, a prompt is generated from the image."},"negative_prompt":{"type":"string","maxLength":1000,"description":"Optional description of what to avoid in the generated video."},"duration":{"type":"integer","description":"Video length in seconds. Allowed values depend on the selected model (see `GET /motion-mockups/models`). Defaults to the model's default duration."},"aspect_ratio":{"type":"string","description":"Output aspect ratio. Only supported by some models, with a model-specific set of allowed values (see `GET /motion-mockups/models`)."},"generate_audio":{"type":"boolean","description":"Whether to also generate audio. Increases the credit cost by a model-specific multiplier."},"skip_discovery":{"type":"boolean","description":"When `true` and no `prompt` is provided, skip image auto-prompting and use a neutral default prompt."}},"required":["start_image_url"]}}}},"responses":{"200":{"description":"Request successfully queued.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"request_id":{"type":"string","description":"Identifier used to poll the request status."},"status":{"type":"string","description":"Initial queue status."},"model":{"type":"string"},"credits":{"type":"integer","description":"Credits reserved for this request."},"status_url":{"type":"string","description":"Convenience URL for polling this request's status."}}},"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Bad request due to invalid input parameters."},"401":{"description":"Unauthorized request, invalid or missing API key."},"403":{"description":"Insufficient credits, or no active workspace for the API key."},"422":{"description":"Validation failed."},"500":{"description":"Failed to submit the request to the generation service."}}}}}}
```
## Get MotionMockups AI Request Status
> 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.
```json
{"openapi":"3.1.0","info":{"title":"Dynamic Mockups MotionMockups AI API","version":"1.0"},"servers":[{"url":"https://app.dynamicmockups.com/api/v1"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key required for authentication."}}},"paths":{"/motion-mockups/status/{requestId}":{"get":{"summary":"Get MotionMockups AI Request Status","description":"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.\n","operationId":"getMotionMockupStatus","parameters":[{"in":"header","name":"Accept","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"The request must accept JSON responses."},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"API key required for authentication."},{"in":"path","name":"requestId","required":true,"schema":{"type":"string"},"description":"The `request_id` returned by the submit endpoint."}],"responses":{"200":{"description":"Current status of the request.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"request_id":{"type":"string"},"status":{"type":"string","description":"One of IN_QUEUE, PROCESSING, COMPLETED, FAILED, CANCELLED, ERROR."},"queue_position":{"type":"integer","nullable":true,"description":"Position in the queue while the status is IN_QUEUE or PROCESSING."},"video":{"type":"object","description":"Present only when status is COMPLETED.","properties":{"url":{"type":"string","description":"Permanent URL of the generated video."},"content_type":{"type":"string"},"file_name":{"type":"string"},"file_size":{"type":"integer","nullable":true}}}}},"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized request, invalid or missing API key."},"403":{"description":"No active workspace for the API key."},"404":{"description":"No request with that `request_id` exists for this workspace."},"500":{"description":"Failed to retrieve the request status or result."}}}}}}
```
## List MotionMockups AI Models
> List the available models with their allowed durations, per-duration credit costs (with and without audio), estimated generation time and supported aspect ratios.
```json
{"openapi":"3.1.0","info":{"title":"Dynamic Mockups MotionMockups AI API","version":"1.0"},"servers":[{"url":"https://app.dynamicmockups.com/api/v1"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key required for authentication."}}},"paths":{"/motion-mockups/models":{"get":{"summary":"List MotionMockups AI Models","description":"List the available models with their allowed durations, per-duration credit costs (with and without audio), estimated generation time and supported aspect ratios.","operationId":"listMotionMockupModels","parameters":[{"in":"header","name":"Accept","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"The request must accept JSON responses."},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"API key required for authentication."}],"responses":{"200":{"description":"Available models.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"models":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"display_name":{"type":"string"},"default_duration":{"type":"string"},"durations":{"type":"array","items":{"type":"object","properties":{"seconds":{"type":"integer"},"credits":{"type":"object","properties":{"audio_off":{"type":"integer"},"audio_on":{"type":"integer"}}},"estimated_time_minutes":{"type":"integer"}}}},"aspect_ratios":{"type":"array","nullable":true,"items":{"type":"string"}},"default_aspect_ratio":{"type":"string","nullable":true},"supports_aspect_ratio":{"type":"boolean"}}}},"default_model":{"type":"string"}}},"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized request, invalid or missing API key."}}}}}}
```
### 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 |
{% hint style="info" %}
The default model is `kling_v2.6`.
{% endhint %}
### 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.