Videos

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)

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 -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
      }'

Retrieve video job details

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

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 -X GET https://api.synapsai.cloud/v1/videos/video-id \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY"

Download generated video content

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

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 -X GET "https://api.synapsai.cloud/v1/videos/video-id/content?variant=video" \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  --output video.mp4

Delete a video job

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

from synapsai import SynapsAI

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

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

curl -X DELETE https://api.synapsai.cloud/v1/videos/video-id \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY"

Create and poll until complete

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

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)

For more details, see the API reference for videos.

Create, poll, and auto-download

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

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.")

Getting started

Guides

Examples

Manage

Platform

Resources

Support

Legal

Video generation

Retrieve video job details

Download generated video content

Delete a video job

Create and poll until complete

Create, poll, and auto-download

​Video generation

​Retrieve video job details

​Download generated video content

​Delete a video job

​Create and poll until complete

​Create, poll, and auto-download

Video generation

Retrieve video job details

Download generated video content

Delete a video job

Create and poll until complete

Create, poll, and auto-download