Introduction
Identify each uploaded subject or setting with an @image number and explain how they interact.
| Field | Value |
|---|---|
| Input | Text |
| Output | Video |
| Publisher | xAI |
| Starting material | Written scene; required opening image; or 1-7 reference images |
| Prompt limit | Up to 4,096 characters |
| Clip length | 1-15 seconds; default 6 seconds |
| Text and image animation size | 480p (default), 720p, 1080p |
| Reference video size | 480p or 720p |
| Text canvas ratios | 16:9 (default), 9:16, 1:1, 4:3, 3:4, 3:2, 2:3; image animation also offers auto |
| Image animation guidance | Required opening image; optional ending image; up to 4 timed keyframes; 1 optional reference image |
| Loop constraint | Matching opening and closing frame; cannot combine loop with |
| Generated audio | Enabled by default; disabling it leaves the rate unchanged |
| Billing | By video second and resolution tier; reference-to-video adds a charge per reference image; failed requests are not charged |
| File retention | Generated video files are deleted after 14 days |
Key features & highlights
A whisper followed by a visible reply
At a rooftop bar at dusk, a woman in a red backless dress leans toward a man and whispers, "Let's get out of here." Our six-second 480p sample includes that line on the soundtrack, followed by his smile and the hand-taking action. Use the example to plan a brief exchange: identify the speaker, quote the line, and describe the other person's response. Review the returned speech and movement together.
A crossing with a spoken line
In our tests, a small fishing boat crossed the sunrise fjord beneath circling gulls. The six-second result included sound and the captain delivering the quoted dialogue.
Reach the greenhouse at second three
In our tests, a rainy lantern alley gave way to a bright Victorian greenhouse at the requested three-second keyframe. The complete shot ran six seconds with sound.
A crane that rocks back to its start
In our tests, the white origami crane moved gently on a blue table through a four-second loop. Its opening and closing frames matched.
Put a dancer and an origami bird in one studio
In our tests, the dancer in black rehearsal clothes moved slowly through a white studio while a paper crane floated nearby. Two uploaded references guided the six-second 848x480 result.
Request parameters
| Parameter | Required | Description |
|---|---|---|
prompt | Yes | Describe the action, setting and optional quoted dialogue in up to 4,096 characters; prompt length is not a billing tier. at least 1 characters · at most 4096 characters |
reference_image_urls | Yes | Supply 1–7 reference images and identify them as @image1, @image2 and so on in upload order; every reference adds a charge. at least 1 items · at most 7 items |
aspect_ratio | No | Select 16:9, 9:16, 1:1, 3:2 or 2:3; the default is 16:9 and shape does not set the per-second rate. |
resolution | No | Reference-led clips accept 480p or 720p, with 480p as the shared default; selecting 720p raises the per-second charge. |
duration_seconds | No | Request 1–15 seconds, with 6 seconds used by default; longer output increases the seconds billed. |
Pricing
Reference-led video costs depend on seconds, resolution and the number of supplied reference images; audio is the same price either way, with no charge for failed requests.
| Specification | Price |
|---|---|
| $0.096 / second |
| $0.168 / second |
Use cases
Dialogue-led story moments
Build a short interaction around one quoted line and a visible response. The rooftop sample pairs a whispered invitation with a smile and a hand-taking action in a six-second clip with sound.
Transitions with a planned arrival
Guide a change of setting with an intermediate image at a chosen second. Our alley-to-greenhouse test reached the sunny greenhouse at second three of a six-second shot.
Repeating motion from a still
Animate an opening image with loop enabled for motion that returns to its start. Our loop test followed the matching-frame setting; inspect the playback join before using the clip in a repeating placement.
Scenes assembled from references
Supply separate images for people, props, or locations and assign each an @image role in the prompt. The reference workflow accepts one to seven images, with a charge for each supplied reference.
Silent inserts for an existing edit
Disable generated audio when the sequence will use an existing soundtrack. Our audio-off test returned no audio track, while the selected duration and resolution still determine the video rate.
Prompt guide & pro tips
Pick the source for the scene
Choose text for a written shot, image-to-video for a required opening still, or reference-to-video for a composition guided by several images.
Describe action and sound
Name the subject, clothing, setting, light, and a manageable action. Put a spoken line in quotation marks and identify who delivers it.
Choose timing and output
Set 1-15 seconds, a supported aspect ratio, and the resolution tier. For still animation, add timed keyframes and choose an ending image or loop when needed.
Review and save the clip
Watch the movement, listen to any dialogue, and inspect a loop join or timed transition. Download accepted videos within 14 days, before the generated files are deleted.
Compose a shot from visual sources
Reference-to-video uses one to seven images to guide a new Grok Imagine Video 1.5 scene. A reference may provide a person, an object, or a setting. Identify images by upload order in the prompt, using @image1, @image2, and later numbers, then explain what each source contributes to the composition.
This workflow is useful when separate pictures describe the cast and environment of a shot. It offers 480p or 720p video lasting 1-15 seconds, with generated sound. Use the sibling image-to-video endpoint when a particular picture must establish the opening frame.
Inputs and settings
| Parameter | Purpose | Supported range or default |
|---|---|---|
reference_image_urls | Supplies the visual sources | 1-7 images |
| prompt | Assigns reference roles and describes the action | Up to 4,096 characters |
aspect_ratio | Chooses the scene's output shape | Select a supported shape; default 16:9 |
| resolution | Chooses the output tier | 480p or 720p; default 480p |
duration_seconds | Sets the requested running time | 1-15 seconds; default 6 |
Reference count and resolution are separate decisions. Choose the images needed to explain the composition, then choose the size for its intended use. This endpoint stops at 720p; 1080p is available in text-to-video and image-to-video.
Give every image a job
Begin the prompt by mapping the inputs: @image1 supplies the performer, @image2 supplies a paper prop, and another image could supply a setting. Check that these labels match the order of reference_image_urls. Referring to an unnamed collection leaves the role of each image unclear.
After the source mapping, describe where the subjects belong and how they interact. Clothing, light, framing, and mood give the scene a coherent direction. For example, a dancer in her thirties wearing black rehearsal clothes can turn slowly in a white studio while an origami crane floats nearby in soft morning light. This is a proposed instruction pattern, not an additional measured result.
Prompt guide for a composed scene
- List the references in upload order and decide whether each contributes a person, object, or location.
- Use the corresponding @image label when naming the source in your instruction.
- Describe the shared setting and a main action that fits the requested duration.
- Add a brief quoted line if speech belongs in the shot, identifying the speaker.
- Review the output against each source and the written brief before accepting it.
Avoid asking the reference list to communicate the entire scene by itself. A picture can show what an object looks like, while the prompt says where it belongs and what happens around it. Keep the movement manageable enough to assess whether the supplied sources and action have been represented as intended.
For people, use adults in their thirties or older in proposed scenes and identify their wardrobe and setting clearly. Use photos and voices you have the right to use, with adults as the subjects and no impersonation. Reference guidance is a creative input, so inspect the delivered identity, object details, and placement rather than assuming the result preserves every feature.
What the supplied reference test showed
Our reference-led test returned a six-second 848x480 video at the 480p tier. This is a measured output size for that request. Compare it with the six-second 16:9 text test, which returned 752x416 at 480p: the tier label should not be treated as a promise of one identical pixel canvas across workflows.
The page's existing reference sample illustrates a performer-and-paper-object composition. Use it to understand the division of reference roles, then judge your own returned shot by its movement, framing, and treatment of the uploaded subjects. The supplied measurements do not establish a general identity-preservation or motion-quality guarantee.
Sound and price planning
Grok Imagine Video 1.5 generates a soundtrack with its video, including quoted dialogue when requested. Audio can also be disabled at the same rate; the supplied audio-off test returned no audio track. Keep a spoken line brief enough for the selected clip length and review the delivery with the action.
Reference-to-video bills by output second at the selected resolution rate and adds a charge for each reference image. More images therefore affect the bill as well as the prompt's source mapping. Longer duration adds billed seconds, and 720p has a higher per-second rate than 480p. Failed requests are not charged. Consult the current model prices for the rates applicable to your request.
Boundaries and alternatives
Reference-guided scenes remain subject to the publisher's own content filter; a refusal from that filter carries no charge. Keep the source set within one to seven images and the prompt within 4,096 characters. Download generated files within 14 days before they are deleted.
Choose text-to-video when a written description is enough to define the shot. Choose image-to-video when you need a required opening image, an optional ending image, up to four timed intermediate images, or a loop. That sibling also accepts one optional reference and supports resolution up to 1080p. Stay with reference-to-video when combining several visual sources is the central requirement and its 480p or 720p output suits the deliverable.
API quick start
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "xai/grok-imagine-video-1.5/reference-to-video",
"input": {
"aspect_ratio": "16:9",
"duration_seconds": 6,
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"reference_image_urls": [
"https://example.com/reference.png"
],
"resolution": "480p"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
See the API reference for authentication, the complete schema, polling, and error handling.











