> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synapsai.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Videos

> Examples of video generation, retrieval, and download with SynapsAI Cloud

Our video endpoints let you generate videos from text prompts (optionally with a reference asset), poll for completion, retrieve job metadata, download the binary content, and delete jobs.

## Video generation

Here is an example of creating a video generation job:

**Parameters:**

* `model`: The model ID of the model you want to use
* `prompt`: Text description of the video to generate
* `input_reference`: Optional reference video or asset (URL, data URI, file path, or base64)
* `seconds`: Length of the video (default: 4)
* `size`: Resolution (default: "1280x720")
* `fps`: Frames per second (default: 16)
* `num_inference_steps`: Diffusion steps (default: 25)
* `guidance_scale`: Guidance scale (default: 5.0)

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  client = SynapsAI("your-api-key")

  video = client.videos.create(
      model="video-model-id",
      prompt="A drone shot over a futuristic city at sunrise",
      seconds=4,
      size="1280x720",
      fps=16,
      num_inference_steps=25,
      guidance_scale=5.0,
  )

  print("Video job created:", video.id, video.status)
  ```

  ```curl title="cURL" theme={null}
  curl -X POST https://api.synapsai.cloud/v1/videos \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "model": "video-model-id",
          "prompt": "A drone shot over a futuristic city at sunrise",
          "seconds": 4,
          "size": "1280x720",
          "fps": 16,
          "num_inference_steps": 25,
          "guidance_scale": 5.0
        }'
  ```
</CodeGroup>

## Retrieve video job details

Use `retrieve` to check the status and metadata of a video job:

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  client = SynapsAI("your-api-key")

  video = client.videos.retrieve("video-id")
  print(f"Status: {video.status}, Size: {video.size}, Duration: {video.seconds} seconds, Prompt: {video.prompt}")
  ```

  ```curl title="cURL" theme={null}
  curl -X GET https://api.synapsai.cloud/v1/videos/video-id \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY"
  ```
</CodeGroup>

## Download generated video content

Once the job is completed, download the binary content (optionally choose a variant like `thumbnail` or `spritesheet`):

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  client = SynapsAI("your-api-key")

  content = client.videos.download_content(
      video_id="video-id",
      variant="video",  # or "thumbnail" / "spritesheet"
  )
  content.write_to_file("video.mp4")
  ```

  ```curl title="cURL" theme={null}
  curl -X GET "https://api.synapsai.cloud/v1/videos/video-id/content?variant=video" \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    --output video.mp4
  ```
</CodeGroup>

## Delete a video job

Delete a completed (or failed) job if you no longer need it:

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  client = SynapsAI("your-api-key")

  resp = client.videos.delete("video-id")
  print(resp.deleted)
  ```

  ```curl title="cURL" theme={null}
  curl -X DELETE https://api.synapsai.cloud/v1/videos/video-id \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY"
  ```
</CodeGroup>

## Create and poll until complete

Use the helper to create a job and poll until it reaches a terminal state:

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  client = SynapsAI("your-api-key")

  video = client.videos.create_and_poll(
      model="video-model-id",
      prompt="A timelapse of flowers blooming",
      seconds=6,
      size="720x1280",
      fps=16,
      num_inference_steps=30,
      guidance_scale=6.0,
      poll_interval=2.0,
      timeout=180,
  )

  print("Final status:", video.status)
  ```
</CodeGroup>

For more details, see the [API reference for videos](https://docs.synapsai.cloud/api-reference/create-a-video-generation-job).

## Create, poll, and auto-download

This flow uses `create_and_poll` and immediately downloads the resulting video when the status is `completed`.

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  client = SynapsAI("your-api-key")

  video = client.videos.create_and_poll(
      model="video-model-id",
      prompt="A hummingbird hovering over tropical flowers",
      seconds=5,
      size="1080x1080",
      fps=18,
      num_inference_steps=28,
      guidance_scale=5.5,
      poll_interval=2.0,
      timeout=240,
  )

  print("Final status:", video.status)

  if video.status == "completed":
      content = client.videos.download_content(video_id=video.id, variant="video")
      content.write_to_file("hummingbird.mp4")
      print("Video saved to hummingbird.mp4")
  else:
      print("Video did not complete successfully; no download attempted.")
  ```
</CodeGroup>