1. ultrafast
  2. Docs
  3. HTTP API

Docs

HTTP API

Render documents over HTTP from uf serve on your own GPU, with one API key and files on local disk.

Authentication

Start the server with uf serve (or the Docker image); the base URL is http://localhost:8080 unless you pass --port or --host. Send its API key as a bearer token: with none set, it makes one at first start and prints it, and uf serve key prints a new one. The SDKs read ULTRAFAST_BASE_URL and ULTRAFAST_API_KEY.

every request
Authorization: Bearer uf_live_...
Content-Type: application/json

POST /v1/render

A document in, a video out: MP4, MOV, WebM, a GIF, a PNG or EXR sequence, or sound alone, at any size and frame rate. Short renders can come back in the response; anything longer goes to storage and returns a receipt.

request
{
  "document": { "version": 1, "format": { }, "nodes": { }, "output": "comp" },
  "output": {
    "inline": true,
    "quality": "draft",
    "size": "720p",
    "audio": true,
    "range": null
  }
}
  • output.inline: true: the file is the response body (up to 32 MiB), with its own content type. Otherwise it is stored and you get a receipt with a signed URL.
  • output.format: mp4 (default), mov, mkv, webm, gif; png or exr for an image sequence, delivered as a zip with the sound as audio.wav; wav, mp3, m4a, flac or opus for the sound alone. output.name's extension picks it too.
  • output.codec: h264 (default), hevc, av1, vp9 or prores (prores_profile: proxy to 4444-xq, default hq). output.alpha: true keeps transparency in ProRes 4444, VP9, GIF, PNG and EXR.
  • output.quality: draft (a fast preview without motion blur), standard (default), high or master. crf or bitrate ("8M") override its encoder setting.
  • output.size: 720p, 1080p, 1440p, 4k or "WxH", rendered at that size, sharp, not scaled up; or scale. output.fps: another frame rate; the film plays at the same speed. Minutes count the size you render.
  • audio, audio_codec, audio_bitrate; loops for GIFs; output.range: [from, to] seconds. Settings that don't go together are a 400 before anything renders.
  • output.uri (Cloud only): write to your own bucket (s3://, gs://, r2://) instead, create-only, so a retry never overwrites a finished video.
receipt
{
  "status": "rendered",
  "url": "http://localhost:8080/v1/files/renders/render_01M7.../film.mp4?expires=...&sig=...",
  "duration": 11.6,
  "frames": 348,
  "bytes": 6620112,
  "sha256": "2b7e...",
  "video": { "width": 1080, "height": 1920, "fps": 30, "format": "mp4", "codec": "h264", "quality": "standard" },
  "minutes": 0.19,
  "timings": { "plan_s": 0.03, "render_s": 1.71, "encode_s": 0.22, "total_s": 2.2 }
}

Jobs and webhooks

Planned for ultrafast Cloud, and not in uf serve: long or batch renders as jobs, with a webhook called when each is done. A self-hosted server answers /v1/jobs with 501 and the code cloud_only.

Webhooks are signed with your webhook secret (GET /v1/me; Ultrafast-Signature: sha256= and the hex HMAC-SHA256 of the body) and retried with backoff for 24 hours.

POST /v1/estimate

What a document will cost before it renders: rendered minutes, GPU seconds and the time to the first byte, from the same plan the renderer runs. A few sampled frames render on the GPU and nothing is encoded. Send the render request's output along ({"size": "4k", "quality": "high"}) to estimate that render.

response
{ "minutes": 0.2, "gpu_seconds": 2.1, "first_byte_s": 3.0, "usd": null }

usd stays null unless whoever runs the server sets a price per minute.

POST /v1/frame

One frame as PNG or JPEG: {"document": {...}, "at": 2.5, "format": "png"}. POST /v1/sheet returns a labelled contact sheet the same way.

Check and review

POST /v1/check with {"document": {...}} returns {"ok", "issues"}, the same as uf check. POST /v1/review renders the film and returns what uf review finds: {"document": {...}, "safe": "social"}.

Uploads

Footage, images, fonts and audio go up once and are referenced by id in documents.

curl
curl http://localhost:8080/v1/uploads -H "Authorization: Bearer $ULTRAFAST_API_KEY" \
  -F file=@interview.mp4
# {"id": "asset_7Kq...", "uri": "asset://7Kq...", "bytes": 48211002, ...}

Then use "src": "asset://7Kq..." in a video, image, audio or captions node. Public https:// URLs work too. Documents sent to the server never read local paths; the SDKs upload a document's local files for you.

Errors and limits

Errors come back as {"error": {"status", "code", "message", "retry"}}.

statusmeaning
400The document doesn't pass check. The body lists the issues, the same as uf check.
401Missing or wrong API key.
403The document reads a local path, or a host the server doesn't allow.
413Inline output over 32 MiB: leave out inline to store it and get a receipt.
422An input couldn't be fetched.
429The queue is full: the server renders one request at a time, and 16 more can wait.
501cloud_only: jobs, output.uri and bucket inputs are planned for ultrafast Cloud.

A render stops after 10 minutes of work. The limits on output length, input size and the queue are settings; see SELF_HOST.md.

Cloud-only parts

A few parts of the API wait for ultrafast Cloud: jobs with signed webhooks, writing renders to your own S3, R2 or GCS bucket with output.uri, reading inputs from buckets, and many keys with sign-in. uf serve answers them with 501 and the code cloud_only, and the SDKs raise CloudOnly (Python) or CloudOnlyError (TypeScript). It has no billing, so /v1/estimate gives a price only if you set ULTRAFAST_USD_PER_MINUTE. The full list of settings is in SELF_HOST.md.