Video Generation

Runnit video generation is a single-call, auto-save operation, just like image generation. One request generates a video and saves it straight into your asset library: you never handle large binary files yourself.

How it works

When you request a video, Runnit:

Generates the clip using your organisation’s configured video model.
Saves the hosted video to your unified assets system.
Returns a lightweight success response with the saved asset metadata.

Videos are stored by reference (as a hosted URL) rather than downloaded, which keeps responses fast and your library lightweight even for large clips.

Two ways to generate

Mode	Use when	Endpoint
Text-to-video	You want a clip from a written prompt	`POST /api/videos/generate`
Image-to-video	You want to animate a source image	`POST /api/videos/generate-from-image`

Generating from a prompt

Send a POST to /api/videos/generate with a prompt, a file name, and either a jobId or requestId:

curl -X POST https://api.runnit.io/api/videos/generate \
  -H "Content-Type: application/json" \
  -H "X-Agent-Api-Key: <your-agent-api-key>" \
  -d '{
    "organizationId": "your-org-id",
    "jobId": "your-job-id",
    "prompt": "A serene ocean sunset, waves gently rolling, warm golden light, peaceful atmosphere",
    "fileName": "sunset.mp4",
    "description": "Hero clip for the launch campaign",
    "resolution": "720p",
    "aspectRatio": "16:9",
    "duration": "4"
  }'

Common parameters

Field	Required	Notes
`prompt`	Yes	Description of the video to generate.
`fileName`	Yes	Saved file name; include `.mp4`.
`jobId` or `requestId`	One required	Associates the asset with a job.
`organizationId`	Yes	Must match your agent API key’s organisation.
`resolution`	No	`720p` or `1080p`, defaults to `720p`.
`aspectRatio`	No	`16:9` or `9:16`, defaults to `16:9`.
`duration`	No	`4`, `8`, or `12` seconds, defaults to `4`.
`description`	No	Stored on the asset; recommended for organisation.

Animating an image

To animate an existing image, send a POST to /api/videos/generate-from-image with the source image. Image-to-video also supports an auto aspect ratio, which keeps the source image’s proportions.

Response

A successful request returns the saved asset and the settings that were used:

{
  "success": true,
  "message": "Video generated and saved successfully",
  "asset": {
    "id": "asset-uuid",
    "fileName": "sunset.mp4",
    "fileType": "video",
    "mimeType": "video/mp4"
  },
  "generationInfo": {
    "resolution": "720p",
    "aspectRatio": "16:9",
    "duration": "4"
  }
}

The saved video is immediately viewable in the app under the associated job’s assets.