Skip to main content
POST
/
v1
/
videos
/
generations
curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3",
    "prompt": "Santa Claus and the bear hug by the lakeside",
    "image_urls": [
      "https://example.com/santa.png",
      "https://example.com/bear.png"
    ],
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_xxxxxxxxxx"
    }
  ]
}

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3",
    "prompt": "Santa Claus and the bear hug by the lakeside",
    "image_urls": [
      "https://example.com/santa.png",
      "https://example.com/bear.png"
    ],
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_xxxxxxxxxx"
    }
  ]
}

​
Authorization

​
Authorization
string
required
All API endpoints require Bearer Token authenticationGet your API Key:Visit the API Key Management Page to get your API KeyAdd it to the request header:
Authorization: Bearer YOUR_API_KEY

​
Request Parameters

​
model
string
required
Video generation model nameSupported models:
  • viduq3-mix - Premium quality, stronger smart transitions, supports 1-second short videos
  • viduq3 - Default choice, smarter camera switching
How to choose: Use viduq3 for everyday use; use viduq3-mix for premium quality or 1-2 second motion effects.
​
prompt
string
required
Text prompt, maximum 5000 charactersDescribe actions and camera movements, not appearance (appearance is determined by reference images).Example: "Santa Claus and the bear hug by the lakeside"
​
image_urls
array<url>
required
Reference image URL array, 1-7 imagesSupports publicly accessible image URLs (http:// or https://)Example: ["https://example.com/santa.png", "https://example.com/bear.png"]
  • Quantity: 1-7 images
  • Supported formats: PNG, JPEG, JPG, WebP
  • Minimum size: 128×128
  • Aspect ratio: between 1:4 and 4:1
  • Maximum file size: ≤ 50MB per image
  • Must be publicly accessible URLs
​
duration
integer
default:"5"
Video duration (seconds)
  • viduq3-mix: 1 to 16
  • viduq3: 3 to 16
Default: 5
viduq3 supports minimum 3 seconds, viduq3-mix supports minimum 1 second. Please pass a valid duration based on the selected model.
​
resolution
string
default:"720p"
Video resolution
  • viduq3-mix: 720p (default) / 1080p
  • viduq3: 540p / 720p (default) / 1080p
viduq3-mix does not support 540p, please use 720p or 1080p.
​
aspect_ratio
string
default:"16:9"
Video aspect ratioOptions:
  • 16:9 - Landscape (default)
  • 9:16 - Portrait
  • 4:3 - Traditional
  • 3:4 - Portrait traditional
  • 1:1 - Square
​
seed
integer
Random seed for controlling generation randomnessIf not provided, a random seed will be used.
Using the same seed with identical parameters will produce similar results, but not guaranteed to be exactly the same.

​
Model Comparison

Featureviduq3viduq3-mix
Recommended forEveryday use, multi-angle camera switchingPremium quality, 1-2 second motion effects
Duration range3-16 seconds1-16 seconds
Resolution540p / 720p / 1080p720p / 1080p
Reference images1-7 images1-7 images

​
Response

​
code
integer
Response status code, 200 on success
​
data
array
Response data array

​
Use Cases

​
Case 1: viduq3 Basic Reference-to-Video

{
  "model": "viduq3",
  "prompt": "Santa Claus and the bear hug by the lakeside",
  "image_urls": [
    "https://example.com/santa.png",
    "https://example.com/bear.png"
  ]
}

​
Case 2: viduq3-mix High Quality Reference-to-Video

{
  "model": "viduq3-mix",
  "prompt": "A cyberpunk neon street with the cat from reference image walking by",
  "image_urls": [
    "https://example.com/cat-1.png",
    "https://example.com/cat-2.png",
    "https://example.com/cat-3.png"
  ],
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "seed": 42
}
Query Task ResultsVideo generation is an async task that returns a task_id upon submission. Use the Get Task Status endpoint to query generation progress and results.