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": "wan2.7-r2v",
    "prompt": "This person walks down the street surrounded by heavy traffic",
    "image_with_roles": [{"url": "https://cdn.example.com/character.jpg", "role": "reference_image"}],
    "resolution": "1080P",
    "duration": 8
  }'

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

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wan2.7-r2v",
    "prompt": "This person walks down the street surrounded by heavy traffic",
    "image_with_roles": [{"url": "https://cdn.example.com/character.jpg", "role": "reference_image"}],
    "resolution": "1080P",
    "duration": 8
  }'

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

​
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 name, fixed as wan2.7-r2v
​
prompt
string
required
Video content description, up to 5000 charactersFor multiple images/videos, use “image 1”, “image 2”, “video 1”, etc. to reference the corresponding reference assets (in order of input)Example: "The character in image 1 enters the scene in image 2 and looks around"
​
image_with_roles
array<object>
Image array with roles; at least one of this and video_urls must be providedFields for each object:
  • url (string): image URL
  • role (string): image role
    • reference_image - reference image (default)
    • first_frame - specified first frame (when provided, size is ignored and the aspect ratio follows the first-frame image)
  • reference_voice (string, optional): voice sample audio URL for that reference character, used to control the character’s voice in the generated video
Example:
[
  {
    "url": "https://cdn.example.com/character.jpg",
    "role": "reference_image",
    "reference_voice": "https://cdn.example.com/voice_sample.mp3"
  },
  { "url": "https://cdn.example.com/start.jpg", "role": "first_frame" }
]
​
video_urls
array<string>
Reference video URL array, up to 5 videos (total images + videos ≤ 5)At least one of this and image_with_roles must be provided
Video constraints:
  • Format: mp4, mov
  • Duration: 1–30s
  • Resolution: width and height in the range [240, 4096] pixels
  • Aspect ratio: 1:8 – 8:1
  • File size: up to 100MB
​
negative_prompt
string
Negative prompt describing unwanted content, up to 500 characters
​
resolution
string
default:"1080P"
Video resolutionOptions:
  • 720P - Standard
  • 1080P - High definition (default)
​
duration
integer
default:"5"
Video duration (seconds)Supported range: 2 ~ 15 secondsDefault: 5
When the reference assets include a video: an integer between [2, 10].When the reference assets do not include a video: an integer between [2, 15].
​
size
string
default:"16:9"
Aspect ratioSupported formats:
  • 16:9 - Landscape widescreen (default)
  • 9:16 - Portrait
  • 1:1 - Square
  • 4:3 - Landscape
  • 3:4 - Portrait
When first_frame is provided via image_with_roles, this parameter is ignored and the aspect ratio follows the first-frame image
​
prompt_extend
boolean
default:"true"
Whether to enable intelligent prompt rewritingSignificantly improves results for short prompts, but increases processing timeDefault: true
​
watermark
boolean
default:"false"
Whether to add “AI Generated” watermark to the generated video
  • true: add watermark
  • false: no watermark (default)
​
seed
integer
Seed integer used to control the randomness of generated contentValue range: integer ≥0
  • For identical requests, the model generates different results when receiving different seed values (e.g., omitting seed)
  • For identical requests, the model generates similar results when receiving the same seed value, but exact consistency is not guaranteed

​
Response

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

​
Use Cases

​
Case 1: Single Reference Image (Simplest)

{
  "model": "wan2.7-r2v",
  "prompt": "This person walks down the street surrounded by heavy traffic",
  "image_with_roles": [
    { "url": "https://cdn.example.com/character.jpg", "role": "reference_image" }
  ]
}

​
Case 2: Multiple Reference Images

{
  "model": "wan2.7-r2v",
  "prompt": "The character in image 1 enters the scene in image 2 and mimics the pose in image 3",
  "image_with_roles": [
    { "url": "https://cdn.example.com/person.jpg", "role": "reference_image" },
    { "url": "https://cdn.example.com/background.jpg", "role": "reference_image" },
    { "url": "https://cdn.example.com/pose.jpg", "role": "reference_image" }
  ],
  "resolution": "1080P",
  "duration": 8,
  "size": "16:9"
}

​
Case 3: Generation Based on Reference Video

{
  "model": "wan2.7-r2v",
  "prompt": "Generate a beach sunset scene in the style of the reference video",
  "video_urls": ["https://cdn.example.com/style_reference.mp4"],
  "resolution": "720P",
  "duration": 8
}

​
Case 4: Specified First Frame + Reference Image

{
  "model": "wan2.7-r2v",
  "prompt": "The reference character starts from this position and walks forward",
  "image_with_roles": [
    { "url": "https://cdn.example.com/character.jpg", "role": "reference_image" },
    { "url": "https://cdn.example.com/start.jpg", "role": "first_frame" }
  ],
  "resolution": "1080P",
  "duration": 8
}

​
Case 5: Reference Image + Reference Voice (Precise)

{
  "model": "wan2.7-r2v",
  "prompt": "This person walks down the street while speaking",
  "image_with_roles": [
    {
      "url": "https://cdn.example.com/character.jpg",
      "role": "reference_image",
      "reference_voice": "https://cdn.example.com/voice_sample.mp3"
    }
  ],
  "resolution": "1080P",
  "duration": 10
}

​
Image Reference Rules

With multiple reference images, use numeric indices in the prompt to refer to them:
  • 1st image → “image 1” or “the first image”
  • 1st video → “video 1” or “the first video”
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.