> ## Documentation Index
> Fetch the complete documentation index at: https://easy-peasy.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Generate Video
> Generate videos from text, first/last frames, or reference media with MiniMax H3 Max, Seedance 2.5, Gemini Omni Flash 1.1, FLUX 3, WAN 3.0, Veo, Kling, and other models. The exact model title is required. See the [video model reference](/api-reference/video-models) for supported settings.
Generation is asynchronous. Save the returned id and poll [Get Video](/api-reference/endpoint/get-video) with the same account’s API key. Paid plans require sufficient credits; free access is limited to selected variants and settings.
## Choose a model
The API supports MiniMax H3 Max, MiniMax H3, Seedance 2.5, Gemini Omni Flash 1.1, FLUX 3, WAN 3.0, Grok Imagine 1.5, and other video families. Use the [video model reference](/docs/api-reference/video-models) to choose an exact variant and its supported inputs, durations, and resolutions.
The REST API requires `model`. The [MCP `generate_video` tool](/docs/mcp/tools) defaults to `MiniMax H3 Max` when you omit it. REST fields use camelCase, such as `aspectRatio` and `referenceVideos`; MCP uses `aspect_ratio` and `reference_videos`.
## Create a video
Send one generation request and save its returned `id`. Generation runs asynchronously; an accepted request does not mean the video is ready. Most videos take a few minutes, and queues can take longer.
```bash theme={null}
curl --fail-with-body -X POST https://easy-peasy.ai/api/generate-video \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A cat walks along a beach at sunset, waves in the background, cinematic lighting",
"model": "MiniMax H3 Max",
"duration": "5",
"aspectRatio": "16:9",
"resolution": "768p"
}'
```
MiniMax H3 Max accepts 5–15 whole seconds and `480p` or `768p`. MiniMax H3 accepts 4–15 whole seconds and `768p` or `2k`. Both families generate native audio; `generateAudio: false` does not disable it. Models with an audio toggle, such as Seedance 2.5, can accept `generateAudio: false`. Providing reference audio enables audio generation.
Send `duration` as a string. Veo 3.1 text variants accept `"4s"`, `"6s"`, or `"8s"`; their Image and First-Last Frame variants accept only `"8s"`. Veo 3.1 does not accept five seconds. Equivalent strings such as `"8"` and `"8s"` are normalized by the API.
## Animate an image
Select a model with a first-image input and send `image`. Adding an image does not automatically switch a text model to its image variant.
```bash theme={null}
curl --fail-with-body -X POST https://easy-peasy.ai/api/generate-video \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "The subject slowly turns toward the camera in soft morning light",
"model": "MiniMax H3 Max Image",
"image": "https://yourcdn.com/first-frame.png",
"duration": "5",
"aspectRatio": "16:9",
"resolution": "768p"
}'
```
Add `"tailImage": "https://yourcdn.com/last-frame.png"` when you want a last frame and the chosen variant supports it. Check the **Input** column in the [model catalog](/docs/api-reference/video-models#model-catalog); model suffixes alone do not identify every input mode.
## Use reference media
Reference variants use images to preserve subjects or style. Some also accept videos for motion or editing and audio for voice or sound guidance.
This example uses a character image, a motion clip, and a voice clip. Replace the placeholder URLs with your own media. Keep each MiniMax H3 Max reference video and audio clip between 2 and 15 seconds, and each type's combined duration at or below 15 seconds.
```bash theme={null}
curl --fail-with-body -X POST https://easy-peasy.ai/api/generate-video \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "The character walks through the market with the motion from the video and speaks in the supplied voice",
"model": "MiniMax H3 Max Reference",
"referenceImages": [{ "url": "https://yourcdn.com/character.png" }],
"referenceVideos": [{ "url": "https://yourcdn.com/motion.mp4" }],
"referenceAudios": [{ "url": "https://yourcdn.com/voice.mp3" }],
"duration": "5",
"aspectRatio": "16:9",
"resolution": "768p"
}'
```
* Use `referenceImages`, `referenceVideos`, and `referenceAudios` as arrays of `{ "url": "..." }` objects.
* `referenceVideo` is a single-URL alternative. If you supply the `referenceVideos` array, it takes precedence, including when empty.
* Do not combine reference videos with `image` or `tailImage`. Audio references require a reference image or a supported reference video; they cannot accompany a first-frame `image`.
* Limits differ by variant. MiniMax H3 Max Reference supports up to 9 images; Seedance 2.5 Reference supports up to 30. See [reference limits](/docs/api-reference/video-models#reference-limits) for counts, durations, formats, and sizes.
* `referenceImages[].type` is optional. Kling O1/O3 uses `character`, `object`, or `style` to assign reference roles; other families use general image references.
All input URLs must be downloadable server-side without browser cookies. A URL that works in your browser may still reject the provider with HTTP 403. Signed URLs must remain valid through queue delays and the provider's download. Reference media can increase credit usage.
## Poll for the result
Call [Get Video](/docs/api-reference/endpoint/get-video) with the returned `id` and the same account's API key every 15–30 seconds. Read `video.url` when `video.status` is `completed`.
The following Node.js 20+ example checks HTTP errors, handles malformed responses, and stops after ten minutes. A local timeout does not cancel the generation; keep the ID so you can check it later.
```javascript theme={null}
async function waitForVideo(videoId, apiKey) {
const deadline = Date.now() + 10 * 60 * 1000;
while (Date.now() < deadline) {
const response = await fetch(
`https://easy-peasy.ai/api/get-video?video_id=${encodeURIComponent(videoId)}`,
{
headers: { 'x-api-key': apiKey },
signal: AbortSignal.timeout(Math.max(1, Math.min(30000, deadline - Date.now()))),
}
);
const data = await response.json().catch(() => null);
if (!response.ok) {
throw new Error(`Video ${videoId}: HTTP ${response.status}: ${data?.error || 'Could not retrieve video'}`);
}
if (data?.video?.status === 'completed' && data.video.url) {
return data.video.url;
}
if (data?.video?.status !== 'processing') {
throw new Error(`Unexpected response for video ${videoId}`);
}
await new Promise(resolve => setTimeout(resolve, Math.max(0, Math.min(15000, deadline - Date.now()))));
}
throw new Error(`Timed out waiting for video ${videoId}. Keep this ID and check it later.`);
}
```
## Handle errors and access limits
| Response | What to do |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Check the exact model name, string duration, resolution, input mode, and reference limits. |
| `401` | Check your API key and account access. |
| `403` | Check your plan and remaining credits. Free accounts have [specific model and resolution limits](/docs/api-reference/video-models#free-plan-settings). |
| `404` from Get Video | Verify the ID and account. Missing or deleted jobs, including some failed generations, return 404. |
| `500` or a network timeout | Save any ID already received. Check the existing job before deciding whether to submit again. |
Get Video currently exposes only `processing` and `completed`, so do not wait for a `failed` status. Submitting a new generation can create another billable job; a polling timeout is not a reason to recreate it automatically.
## OpenAPI
````yaml POST /api/generate-video
openapi: 3.0.1
info:
title: Easy-Peasy.AI API
description: >-
API for Easy-Peasy.AI text, image, video, audio, and chat features.
Authenticate with an API key from https://easy-peasy.ai/settings/api.
Individual endpoints document public access and alternative authentication
methods.
version: 1.0.5
servers:
- url: https://easy-peasy.ai
security:
- apiKeyAuth: []
paths:
/api/generate-video:
post:
summary: Generate Video
description: >-
Generate videos from text, first/last frames, or reference media with
MiniMax H3 Max, Seedance 2.5, Gemini Omni Flash 1.1, FLUX 3, WAN 3.0,
Veo, Kling, and other models. The exact model title is required. See the
[video model reference](/api-reference/video-models) for supported
settings.
Generation is asynchronous. Save the returned id and poll [Get
Video](/api-reference/endpoint/get-video) with the same account’s API
key. Paid plans require sufficient credits; free access is limited to
selected variants and settings.
operationId: generateVideo
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateVideoRequest'
examples:
minimax_text:
summary: MiniMax H3 Max text-to-video
value:
prompt: A cat walks on the beach at sunset, cinematic lighting
model: MiniMax H3 Max
duration: '5'
aspectRatio: '16:9'
resolution: 768p
minimax_image:
summary: MiniMax H3 Max image-to-video
value:
prompt: The subject slowly turns toward the camera
model: MiniMax H3 Max Image
image: https://yourcdn.com/first-frame.png
duration: '5'
aspectRatio: '16:9'
resolution: 768p
seedance_references:
summary: Seedance 2.5 with references
value:
prompt: The character walks through a neon-lit market
model: Seedance 2.5 Reference
referenceImages:
- url: https://yourcdn.com/character.png
referenceVideos:
- url: https://yourcdn.com/motion.mp4
referenceAudios:
- url: https://yourcdn.com/voice.mp3
duration: '5'
aspectRatio: '16:9'
resolution: 720p
text_to_video:
summary: Text-to-video
value:
prompt: A cat walking on the beach at sunset, cinematic lighting
model: Veo 3.1 Fast
duration: 4s
aspectRatio: '16:9'
resolution: 720p
image_to_video:
summary: Image-to-video
value:
prompt: The subject slowly turns and smiles at the camera
image: https://example.com/photo.jpg
model: Veo 3.1 Fast Image
duration: 8s
aspectRatio: '16:9'
resolution: 720p
responses:
'200':
description: Video generation started
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateVideoResponse'
example:
id: 12345
prompt: A cat walking on the beach at sunset
image_url: ''
model: Veo 3.1 Fast
is_video: true
created_at: '2025-01-15T10:30:00.000Z'
'400':
description: Bad request — invalid model, duration, aspect ratio, or input type
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Invalid model selected
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Invalid API key
'403':
description: >-
Credit limit reached or model/settings unavailable on the current
plan
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: >-
This model is not available on the Free plan. Try Veo 3.1 or
Seedance 2.0 Mini, or upgrade to unlock all models.
'405':
description: Method not allowed. Use POST.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: >-
Provider or server error. Preserve any existing job ID before
deciding to submit another generation.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
GenerateVideoRequest:
type: object
required:
- prompt
- model
properties:
prompt:
type: string
description: Text prompt describing the video to generate.
example: A cat walking on the beach at sunset, cinematic lighting
minLength: 1
image:
type: string
format: uri
description: >-
Public URL of a first-frame image. Choose a variant with a
first-image input in the video model reference. Model suffixes are
not always enough: Grok Imagine 1.5 and Kling 2.5 Turbo Standard
also require image. The URL must remain downloadable without browser
cookies through queue delays.
model:
type: string
description: >-
Required exact model title. See the video model reference for input
modes, durations, resolutions, and reference limits. Adding media
does not automatically switch model variants.
https://docs.easy-peasy.ai/api-reference/video-models
enum:
- Veo 3.1 Fast
- Gemini Omni Flash
- Gemini Omni Flash Reference
- Gemini Omni Flash 1.1
- Gemini Omni Flash 1.1 Reference
- MiniMax H3 Max
- MiniMax H3 Max Reference
- Grok Imagine
- Grok Imagine Reference
- Grok Imagine 1.5 Text
- Grok Imagine 1.5 Reference
- Seedance 2.0 Fast
- MiniMax H3
- Seedance 2.5
- Seedance 2.5 Turbo
- Seedance 2.5 Turbo Reference
- Seedance 2.5 Reference
- FLUX 3
- WAN 3.0
- WAN 3.0 Reference
- Seedance 2.0 Turbo
- Seedance 2.0
- Seedance 2.0 Mini
- Seedance 2.0 Reference
- Seedance 2.0 Fast Reference
- MiniMax H3 Reference
- Seedance 2.0 Mini Reference
- Kling 2.6 Pro
- Veo 3.1 Lite
- Veo 3.1 Lite Image
- Veo 3.1 Fast Image
- Gemini Omni Flash Image
- Gemini Omni Flash 1.1 Image
- Gemini Omni Flash 1.1 First-Last Frame
- MiniMax H3 Max Image
- Grok Imagine Image
- Grok Imagine 1.5
- Seedance 2.0 Image
- Seedance 2.0 Fast Image
- MiniMax H3 Image
- Seedance 2.5 Turbo Image
- Seedance 2.5 Image
- FLUX 3 Image
- WAN 3.0 Image
- Seedance 2.0 Turbo Image
- Seedance 2.0 Mini Image
- Happy Horse
- Happy Horse Image
- Happy Horse Reference
- Kling 2.6 Pro Image
- Kling 3.0 Pro
- Kling 3.0 Pro Image
- Kling 3.0 Standard
- Kling 3.0 Standard Image
- Kling O3 Pro
- Kling O3 Pro Image
- Kling O3 Standard
- Kling O3 Standard Image
- Kling O3 Reference
- Seedance 1.5 Pro
- Seedance 1.5 Pro Image
- Kling O1 Image
- Kling O1 Reference
- Kling 2.5 Turbo Pro Image
- Kling 2.5 Turbo Pro
- Kling 2.5 Turbo Standard
- Seedance 1.5 Pro First-Last Frame
- Veo 3.1
- LTX-2 Pro
- LTX-2 Fast
- Veo 3.1 Image
- Veo 3.1 First-Last Frame
- Veo 3.1 Fast First-Last Frame
- LTX-2 Pro Image
- LTX-2 Fast Image
- Hailuo 2.0
- Hailuo 2.0 Pro
- Hailuo 2.3
- Hailuo 2.3 Pro
- Hailuo 2.3 Image
- Hailuo 2.3 Pro Image
- Hailuo 2.3-Fast Pro Image
- Seedance v1 Pro Fast
- Pixverse v5.5
- Wan 2.5
- Wan v2.2 Turbo
- Wan v2.2
- Hailuo 2.0 Image
- Hailuo 2.0 Pro Image
- Seedance 1.0 Pro Fast
- Pixverse v5.5 Image
- Wan 2.5 Image
- Wan v2.2 Turbo Image
- Wan-2.2 Image
example: MiniMax H3 Max
duration:
type: string
description: >-
Output length as a string, using the exact variant’s allowed
durations. MiniMax H3 Max: 5–15 whole seconds; MiniMax H3: 4–15. Veo
3.1 text variants: 4s, 6s, 8s; Image and First-Last Frame variants:
8s only. Bare seconds and an s suffix are equivalent. If omitted,
the API selects five seconds when listed, otherwise the first
configured duration, or five seconds for models without a list.
Provider-specific output lengths can differ.
example: '5'
aspectRatio:
type: string
default: '16:9'
description: >-
Use an aspect ratio listed for the exact variant. Omit for variants
whose framing follows the input. The API defaults to 16:9 when
applicable.
enum:
- '16:9'
- '9:16'
- '1:1'
- '4:3'
- '3:4'
- '21:9'
- '3:2'
- '2:3'
resolution:
type: string
description: >-
Allowed resolutions depend on the exact variant. MiniMax H3 Max:
480p/768p; MiniMax H3: 768p/2k; Seedance 2.5: 480p/720p; Seedance
2.5 Turbo: 720p/1080p. Send a listed value explicitly; defaults vary
by model. Use lowercase k for 2k and 4k. Omit when no resolution
selector is listed.
enum:
- 360p
- 480p
- 720p
- 768p
- 1080p
- 2k
- 4k
generateAudio:
type: boolean
description: >-
Enable or disable generated audio only on models with an audio
toggle. MiniMax H3 and H3 Max always generate native audio; false
does not disable it. Supplying reference audio enables audio
generation. Audio settings can affect credit usage.
tailImage:
type: string
format: uri
description: >-
Public URL of a last-frame image, paired with image. Use only a
variant that supports a last image, such as MiniMax H3 Max Image or
Seedance 2.5 Image. See the video model reference.
referenceImages:
type: array
description: >-
Array of reference images on supported variants. Reference models
require at least one reference image or a supported reference video.
Limits differ: MiniMax H3 Max Reference accepts up to 9 images;
Seedance 2.5 Reference accepts up to 30. Some Veo variants also
support optional references. See the video model reference.
items:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Publicly reachable image URL.
type:
type: string
enum:
- character
- object
- style
description: >-
Optional reference role. Kling O1/O3 uses
character/object/style to assign reference roles; other
families use general image references.
referenceVideo:
type: string
format: uri
description: >-
Single reference video URL, on variants supporting reference video.
Alternative to referenceVideos; the array takes precedence when
supplied, even if empty.
referenceVideos:
type: array
description: >-
Reference videos for supported variants only. Do not combine with
image or tailImage. Counts, clip lengths, total duration, and
file-size limits depend on the variant. MiniMax H3 Max Reference
accepts up to 3 clips of 2–15 seconds, at most 15 seconds combined,
and 20 MiB each. Seedance 2.5 Reference supports up to 3 clips of
2–30 seconds, at most 30 seconds combined, and 50 MiB each.
Reference inputs can add credit charges.
items:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Publicly downloadable media URL.
referenceAudios:
type: array
description: >-
Audio references for supported variants. Require a companion
reference image or supported reference video, and cannot accompany
image. Enable generated audio. MiniMax H3 Max Reference accepts up
to 3 clips of 2–15 seconds and at most 15 seconds total. Seedance
2.5 Reference supports up to 10 MP3/WAV clips, 2–30 seconds each, at
most 30 seconds total, and 15 MiB each. See the reference limits for
other variants.
items:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Publicly downloadable media URL.
GenerateVideoResponse:
type: object
properties:
id:
type: integer
description: >-
Video ID. Use this to poll for the result with the Get Video
endpoint.
prompt:
type: string
description: The prompt used for generation
image_url:
type: string
description: >-
Video URL when present. May be empty or omitted while processing.
Poll Get Video with id; do not depend on this field to detect
submission success.
model:
type: string
description: The model used for generation
is_video:
type: boolean
created_at:
type: string
format: date-time
Error:
type: object
properties:
error:
oneOf:
- type: string
- type: object
properties:
message:
type: string
status:
type: integer
description: >-
Error text, or an object with message and optional status for some
provider integrations.
example: Invalid API key
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
API key for authentication. Get yours at
https://easy-peasy.ai/settings/api
````