API/videos
Video generation runs asynchronously: create a job, poll its status by id, then download the MP4 when it completes.
https://api.framewharf.com/v1/videosAuthorization: Bearer sk-your_api_keyTo generate and edit video with Gemini Omni, use POST /v1/interactions.
POST /v1/videos takes model, prompt and seconds (1–15, default 8). A size (1280x720) value sets resolution and aspect ratio together, or you can set each one separately: resolution via extra_body.resolution: 480p (default), 720p or 1080p; aspect ratio via extra_body.aspect_ratio (16:9 default, 1:1, 9:16…).
curl "https://api.framewharf.com/v1/videos" \
-H "Authorization: Bearer sk-your_api_key" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-1.5-lite",
"prompt": "Waves crashing on a rocky shore at sunset",
"seconds": "6",
"extra_body": { "resolution": "720p" }
}'The request returns a job immediately — keep the id to poll its status:
{
"id": "video_bGl0ZWxsbTpjdXN0b21fbGxt...",
"object": "video",
"status": "queued",
"model": "grok-imagine-video-1.5-lite",
"seconds": "6",
"size": "720p"
}Every video below was generated by this endpoint, one job each, alongside the prompt that produced it.
To animate an image you already have (image to video), add an image field holding a public URL or a base64 data URL; with an image, the prompt is optional:
{
"model": "grok-imagine-video-1.5-lite",
"prompt": "Let the boat in the picture drift slowly toward the horizon",
"seconds": "6",
"image": { "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..." }
}Drag the slider: the still image sent in is on the left, the video one request made from it on the right.

Several images can steer one clip instead of pinning the first frame: extra_body.reference_images takes a list, referred to in the prompt as <IMAGE_0> in the order you send them, while extra_body.last_frame pins the final frame.
{
"model": "grok-imagine-video-1.5-lite",
"prompt": "The character in <IMAGE_0> walks across the room in <IMAGE_1>",
"seconds": "6",
"extra_body": {
"reference_images": [
{ "url": "https://example.com/character.jpg" },
{ "url": "https://example.com/room.jpg" }
],
"last_frame": { "url": "https://example.com/final-shot.jpg" }
}
}To pin frames inside the clip as well, send extra_body.keyframes — up to four images, each with a timestamp in seconds, strictly inside the clip. To have a character speak in a preset voice, send extra_body.reference_audios — up to three voices, referred to in the prompt as <AUDIO_0> in the order you send them.
{
"model": "grok-imagine-video-1.5-lite",
"prompt": "A tree through the four seasons, <AUDIO_0> whispers: spring is here",
"seconds": "8",
"image": { "url": "https://example.com/start.jpg" },
"extra_body": {
"resolution": "720p",
"keyframes": [
{ "image_url": "https://example.com/middle.jpg", "timestamp": 4 }
],
"last_frame": { "url": "https://example.com/end.jpg" },
"reference_audios": [{ "voice_id": "eve" }]
}
}Clips steered by reference images, pinned frames or reference voices top out at 720p. These are features of newer models; a model that doesn't support a feature, or a request carrying an undocumented field, is rejected with a clear message instead of being ignored.
Call GET /v1/videos/{id} every few seconds until the job leaves the processing states. A video usually finishes in tens of seconds to a few minutes, depending on length and resolution.
curl "https://api.framewharf.com/v1/videos/video_bGl0ZWxsbTpjdXN0b21fbGxt..." \
-H "Authorization: Bearer sk-your_api_key"When status is completed, download the MP4 from GET /v1/videos/{id}/content. The request redirects to a temporary download link, valid for about 30 minutes (also returned in the response's url field), so your client must follow redirects. Download and store the file on your side as soon as the job completes — old jobs expire and cannot be downloaded again.
curl -L "https://api.framewharf.com/v1/videos/video_bGl0ZWxsbTpjdXN0b21fbGxt.../content" \
-H "Authorization: Bearer sk-your_api_key" \
-o video.mp4POST /v1/videos/edits takes the video.id of a completed job and a prompt describing the change; the rest of the scene is kept.
curl "https://api.framewharf.com/v1/videos/edits" \
-H "Authorization: Bearer sk-your_api_key" \
-H "Content-Type: application/json" \
-d '{
"video": { "id": "video_bGl0ZWxsbTpjdXN0b21fbGxt..." },
"prompt": "Turn the daytime scene into night under streetlights"
}'An edit takes no duration or resolution: the result inherits both from the source video — up to 720p and up to 8.7 seconds — and you get a new job id to poll and download exactly like a newly created job. Only videos made with the model listed below can be edited.
POST /v1/videos/extensions extends a finished video from its last frame; seconds (2–10, default 6) is the length of the new part, not of the result.
curl "https://api.framewharf.com/v1/videos/extensions" \
-H "Authorization: Bearer sk-your_api_key" \
-H "Content-Type: application/json" \
-d '{
"video": { "id": "video_bGl0ZWxsbTpjdXN0b21fbGxt..." },
"prompt": "The camera keeps pulling back and the boat sails out of frame",
"seconds": "6"
}'The returned id can itself be extended or edited, so a long sequence is built one segment at a time. Only videos made with the model listed below can be edited or extended.
seedance-2.5 uses the same create, poll and download steps above, with its own parameters: prompt is required; seconds runs from 4 to 30 (default 5), or -1 to let the model choose the length; resolution 480p, 720p (default) or 1080p; aspect_ratio 16:9 (default), 4:3, 1:1, 3:4, 9:16, 21:9 or adaptive (the model chooses the ratio); generate_audio (on by default, generating sound) and seed.
To open and close the clip on your own pictures, send image as the first frame and, optionally, last_frame as the last — a public URL or a JPEG/PNG/WebP data URL. With a first frame the aspect ratio follows the picture, so leave out aspect_ratio. With return_last_frame, a completed job's status also carries a temporary link to the video's final frame, in last_frame_url.
{
"model": "seedance-2.5",
"prompt": "The camera glides across the room and stops at the window",
"seconds": "5",
"image": { "url": "https://example.com/start.jpg" },
"extra_body": {
"resolution": "720p",
"last_frame": { "url": "https://example.com/end.jpg" },
"return_last_frame": true
}
}Instead of frames, you can steer the clip with references: reference_images (up to 30 images), reference_videos (up to 10 videos by URL, 30 seconds in total) and reference_audios (up to 10 MP3/WAV files, by URL or data URL). Refer to them in the prompt in the order you send them; audio can come alone. Frames and references don't share a request.
{
"model": "seedance-2.5",
"prompt": "The person in the picture dances the moves of the reference video to the beat of the track",
"seconds": "8",
"extra_body": {
"resolution": "720p",
"aspect_ratio": "9:16",
"reference_images": [{ "url": "https://example.com/dancer.jpg" }],
"reference_videos": [{ "url": "https://example.com/moves.mp4" }],
"reference_audios": [{ "url": "https://example.com/beat.mp3" }]
}
}When the prompt asks to change the reference video itself (restyle it, swap an object…), the model keeps that video's ratio and length — send aspect_ratio: "adaptive" and seconds: -1, or the job fails and the credit is refunded. The source video runs 4 to 30 seconds.
{
"model": "seedance-2.5",
"prompt": "Repaint the whole scene of the video as a watercolor",
"seconds": -1,
"extra_body": {
"resolution": "720p",
"aspect_ratio": "adaptive",
"reference_videos": [{ "url": "https://example.com/clip.mp4" }]
}
}Credit is deducted when the job is created: the requested seconds times the per-second rate for that resolution. Video models are enabled per API key — GET /v1/models with your key lists exactly the models you can call; message Framewharf if you need more access.