Turn an Image into a Video

Not yet available. Image-to-video is tracked to be built — today, text-to-video works on POST /v1/videos, which accepts model, prompt, and seconds.

Image-to-video generation takes a still image as its starting frame and animates it according to a text prompt. The output is a short video clip where the first frame closely matches your input image.

Intended request shape#

This is the intended design, not a working request — the shipped API does not accept an image field yet:

# Intended design — not yet available
curl https://opendunes.com/api/v1/videos \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x-ai/grok-imagine-video",
    "image_url": "https://your-cdn.com/dunes-still.jpg",
    "prompt": "Sand slowly rippling in a gentle wind, golden hour light",
    "seconds": 4
  }'

Image input (how the starting frame is supplied — by URL or upload) will be part of the intended design. Additional intended parameters under consideration include a negative prompt, a motion-intensity control, and a fixed seed for reproducibility; none of these exist on the API today.

Preparing your input image#

Image-to-video models work best with:

• Resolution: at least 512×512 px; 1024×768 or higher for best results.
• Subject clarity: the main subject should be clearly visible and well-lit.
• Composition: leave some visual "room" around the subject for the animation to breathe.
• Format: JPEG and PNG both work; avoid heavily compressed images.

Prompt guidance for animation#

The prompt describes what moves and how — not what the scene looks like (the model already knows from the image):

Instead of: "A camel in the Sahara desert moving its head"

Write: "Gentle head movement, ears flicking, warm desert wind"

Keep prompts short and motion-focused. Over-describing the scene can confuse the model since the visual is already provided.

Handling the response#

The response is identical in shape to a text-to-video response. For longer clips or high-resolution outputs, the status may be "in_progress" initially — poll the status endpoint:

import time, os, requests

def wait_for_video(generation_id: str, max_wait: int = 120) -> str:
    url = f"https://opendunes.com/api/v1/videos/{generation_id}"
    headers = {"Authorization": f"Bearer {os.environ['OPENDUNES_API_KEY']}"}
    deadline = time.time() + max_wait

    while time.time() < deadline:
        r = requests.get(url, headers=headers)
        r.raise_for_status()
        data = r.json()
        if data["status"] == "completed":
            return data["url"]
        if data["status"] == "failed":
            raise RuntimeError(data.get("error", "Generation failed"))
        time.sleep(5)

    raise TimeoutError("Video generation timed out")

Cost#

Image-to-video is billed per second of output at the model's per-second DA rate, the same as text-to-video. The starting image itself is not charged separately. Current rates will be listed in the model catalog once the feature is live.