Video editing with /v1/videos/edits

Updated November 3, 2026. Based on xAI’s Video Editing page: the source video is at most 8.7 seconds long, the output keeps its duration, aspect ratio, and resolution (720p max), and extension uses the same video object as editing. The previous claim that editing was unreliable for specific elements contradicts xAI’s examples, which focus precisely on precise edits. Sources: Video Editing · Video Overview.

Edit an existing video

Generation is only part of the job. The xAI API also exposes a video editing endpoint that takes an existing sequence and modifies it based on text prompts. It’s the video equivalent of image editing, with stricter format constraints. Before you write your first request, note the four bounds that determine what you can submit.

The POST /v1/videos/edits endpoint

The request pairs a source video with a prompt describing the desired modification.

{
  "model": "grok-imagine-video",
  "prompt": "Change the background to a sunset over the ocean",
  "video": {
    "url": "https://example.com/original-video.mp4"
  }
}

Three fields suffice: model, which remains grok-imagine-video; prompt, which contains the description of the modification; and video.url, which points to the MP4 file to process. Notice that the video is encapsulated in a video object, which accepts a url or the file_id of an uploaded file: the extension endpoint, in the next lesson, adopts the same convention.

Technical constraints are stricter here than in generation. The source must not exceed 8.7 seconds, and the produced video keeps its duration; the Video Generation page mentions a duration “capped at 8.7 seconds” without detailing the handling of a longer source: so trim your sources beforehand. Resolution caps at 720p. The input file must be an MP4 in a supported codec, such as H.264, H.265, or AV1. The most confusing point for those coming from generation: you have no control over the duration, aspect ratio, or resolution of the output, all determined by the source video. The edit request includes no duration, aspect_ratio, or resolution field.

What to ask for in an edit

Background replacement is the textbook case: the subject stays, the setting changes.

{
  "model": "grok-imagine-video",
  "prompt": "Replace the background with a space landscape with stars and nebulae. Keep the same subject and the same movement.",
  "video": {"url": "https://example.com/video.mp4"}
}

Style changes affect the entire image and transform the clip’s style without modifying its action—practical for adapting the same sequence into different universes.

{
  "model": "grok-imagine-video",
  "prompt": "Transform this video into a Japanese cartoon style with vivid colors",
  "video": {"url": "https://example.com/video.mp4"}
}

Adding elements enriches the scene with layers that did not exist during filming, usually atmospheric.

{
  "model": "grok-imagine-video",
  "prompt": "Add falling snow and a frost effect on the edges",
  "video": {"url": "https://example.com/video.mp4"}
}

Finally, lighting modification amounts to regrading the sequence: same shots, radically different ambiance.

{
  "model": "grok-imagine-video",
  "prompt": "Change the lighting to a night ambiance with blue and purple neon lights",
  "video": {"url": "https://example.com/video.mp4"}
}

The asynchronous cycle, identical to generation

Editing follows exactly the same four-step protocol as generation: you send the request, you receive a request_id, you poll GET /v1/videos/{request_id} at regular intervals, and you retrieve the edited video when the status changes to done. In Python, the first two steps fit in a few lines.

import httpx

# 1. Submit the edit
response = httpx.post(
    "https://api.x.ai/v1/videos/edits",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "grok-imagine-video",
        "prompt": "Add a rain effect over the entire scene",
        "video": {"url": "https://example.com/source.mp4"}
    }
)
request_id = response.json()["request_id"]

# 2. Poll the status (simplified)
status = httpx.get(
    f"https://api.x.ai/v1/videos/{request_id}",
    headers={"Authorization": f"Bearer {api_key}"}
).json()

State what changes, and what stays

xAI describes the model’s behavior in one sentence: grok-imagine-video applies the requested change and keeps everything else as close to the source as it can. Its documentation derives a guideline from this: say also what must remain identical. Its own examples also focus on precise edits of a single clip—adding a silver necklace, changing an outfit to red, putting a black wide-brimmed hat on a character—run in parallel on the same source.

{
  "model": "grok-imagine-video",
  "prompt": "Change the woman's jacket to red. Keep the same face, the same setting, the same framing, and the same movement.",
  "video": {"url": "https://example.com/video.mp4"}
}

xAI’s image prompt guide, written for still images, specifies the order that works: the modification first, then a sentence that locks what stays static. An edit that starts with “keep everything” changes almost nothing, and an edit that copies a full generation prompt reinvents the scene.

Four habits avoid most pitfalls: keep your sources under 8.7 seconds, in a supported codec (H.264, H.265, or AV1); name what must remain intact; test a modification on a short clip before scaling it; and remember that editing uses grok-imagine-video, whose pricing grid shows a single rate, $0.050 per second—a round of trials costs the same as generation.

Key takeaways

• The POST /v1/videos/edits endpoint modifies an existing video based on a prompt, with grok-imagine-video only
• The source lasts at most 8.7 seconds; the output keeps its duration, ratio, and resolution (720p max)
• The source video must be an MP4 in a supported codec (H.264, H.265, AV1)
• The request has no duration, aspect_ratio, or resolution field
• Say what must change, then what must remain identical