>docs/api/image-to-video

Image-to-Video API

Generate videos from a reference image using the image_url parameter. Provide a publicly accessible image URL alongside a motion prompt to animate it into a high-quality video clip. Powered by nohuman-x33.

# How It Works

Provide Image URL

Pass a publicly accessible image URL in the image_url parameter. This triggers Image-to-Video mode.

Describe Motion

Provide a prompt describing the desired motion, camera movement, and animation.

Poll & Download

Poll the generation endpoint until completed, then download the video from result.url.

# Generate Video from Image

POST/v1/videos/generate

Generate a video using a reference image. Uses the same endpoint as text-to-video -- including the image_url parameter triggers I2V mode.

Parameters

Name	Type	Required	Description
`prompt`	string	required	Describe the desired motion, camera movement, and animation (e.g., "camera slowly zooms in, hair blowing in the wind").
`image_url`	string	required	Publicly accessible URL to the reference image (JPG, PNG, WebP). Including this parameter triggers Image-to-Video mode.
`mode`	string	optional ("fast")	Generation mode. "fast" for faster generation, "hq" for higher quality output.
`negative_prompt`	string	optional	Describe what you do not want in the video (e.g., "blurry, low quality").
`aspect_ratio`	string	optional ("16:9")	Output aspect ratio. Options: "16:9", "9:16", "1:1".
`duration`	number	optional (5)	Video duration in seconds. Options: 5 or 10.
`cfg_scale`	number	optional (0.5)	Classifier-free guidance scale. Range: 0 to 1.
`sound`	boolean	optional (true)	Enable audio generation for the output video.

Response

{
  "id": "gen_img2v_x7y8z9",
  "model": "nohuman-x33",
  "status": "created",
  "poll_url": "/v1/videos/generations/gen_img2v_x7y8z9"
}

# Code Examples

Image-to-Video Generation

curl -X POST https:"code-comment">//api.nohuman.studio/v1/videos/generate \
  -H "Authorization: Bearer $NOHUMAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Camera slowly zooms in, subject turns head and smiles, cinematic lighting",
    "image_url": "https://example.com/reference_photo.jpg",
    "duration": 10,
    "aspect_ratio": "16:9"
  }'

# Image Requirements

Requirement	Specification
Formats	JPG, PNG, WebP
Access	Publicly accessible URL
Max file size	10 MB
Recommended resolution	1024x1024 or higher

TIP

For best results, use high-quality images that match your target aspect ratio. The model uses the image as a visual reference and applies the motion described in your prompt.

# Pricing

Duration	Cost
Fast 5s	$0.47
Fast 10s	$0.94
HQ 5s	$0.94
HQ 10s	$1.87

# Generation Status

After submitting, poll GET /v1/videos/generations/{id} every 5 seconds to check progress.

Status	Description
created	Request received, waiting for processing
processing	Video is being generated
completed	Video ready -- download from result.url
failed	Generation failed - check error field and retry

SYS :: image-to-video/v1 :: endpoint reference