# rendermate

> One API key for video: rendering, compositing, generative video (Seedance), images, speech, sound effects, transcription, asset storage and hosted playback. Usage is metered per second, GB and token. Generative models are billed at exactly the provider's list price (0% markup).

Base URL: https://rendermate.tella.dev/v1
Auth: `Authorization: Bearer $RENDERMATE_API_KEY` (keys look like `sk_…` and belong to an organization; create one at https://rendermate.tella.dev/dashboard/keys)
Bodies are JSON. Long jobs (generations, renders) return `status: "queued"`; poll the resource or register a webhook.
Errors: `{ "error": "bad_request", "message": "…" }` with the HTTP status.

## Workflow

1. Get media in: `POST /assets` (upload) or `POST /assets/imports` (URL) or `POST /generations` (AI).
2. Arrange it: `POST /compositions` with a document, then `POST /compositions/{id}/commands` to edit. Pass `baseRevision` to fail with 409 on concurrent edits and `dryRun: true` to validate.
3. Output it: `POST /renders` → an MP4/HLS `url`; `publish: true` (or `POST /videos`) also gives a `playbackUrl` and `embedUrl`.

### 1 · generate a clip

```sh
curl https://rendermate.tella.dev/v1/generations \
  -H "Authorization: Bearer $RENDERMATE_API_KEY" \
  --json '{
    "model": "bytedance/seedance-2.5",
    "prompt": "a paper boat drifting down a rainy street, macro lens",
    "resolution": "1080p",
    "ratio": "9:16",
    "duration": 5,
    "generateAudio": true
  }'
# → { "id": "gen_8f2k…", "status": "queued" }
#   poll GET /generations/gen_8f2k… →
#   { "status": "done", "assetId": "as_q7…",
#     "usage": { "completionTokens": 243000 } }
```

### 2 · compose it

```sh
curl https://rendermate.tella.dev/v1/compositions \
  -H "Authorization: Bearer $RENDERMATE_API_KEY" \
  --json '{
    "canvas": { "width": 1080, "height": 1920, "fps": 30, "durationMs": 5000 },
    "layers": [
      { "type": "media", "assetId": "as_q7…", "fit": "cover" },
      { "type": "text", "text": "Rainy day sale", "y": 0.8,
        "animate": { "in": "rise", "durationMs": 400 } }
    ]
  }'
# → { "id": "cmp_31x…", "revision": 1 }
```

### 3 · render and play

```sh
curl https://rendermate.tella.dev/v1/renders \
  -H "Authorization: Bearer $RENDERMATE_API_KEY" \
  --json '{ "compositionId": "cmp_31x…", "format": "mp4", "publish": true }'
# → { "id": "rnd_m2…", "status": "done",
#     "url": "https://rendermate.tella.dev/files/rnd_m2….mp4",
#     "playbackUrl": "https://rendermate.tella.dev/v/vid_a9…" }
```

# Endpoints

## /assets

Upload or import any media. Stored, probed, transcoded for playback.

- `POST /assets`: Create an upload; returns a presigned PUT URL
- `POST /assets/imports`: Import from a URL (mp4, mov, YouTube, image, audio)
- `GET /assets/{id}`: Status, duration, dimensions, playbackUrl
- `GET /assets/{id}/transcript`: Words with start/end ms
- `DELETE /assets/{id}`: Delete an asset and its renditions

## /generations

One endpoint, every model and every provider parameter. Results land as assets; you pay the provider's price for what was used.

- `GET /models`: Every routable model with its price
- `POST /generations`: {model, prompt, …model params} → generation
- `GET /generations/{id}`: Status, assetId, and usage: tokens and USD billed

## /compositions

Freeform timeline JSON: tracks, layers, keyframes, text, transitions.

- `POST /compositions`: Create from a document or an empty canvas
- `POST /compositions/{id}/commands`: Apply edits (add layer, trim, animate…)
- `GET /compositions/{id}`: The current document
- `GET /compositions/schema`: JSON schema for documents and commands

## /renders

GPU compositing to MP4 or HLS. Same engine for preview and export.

- `POST /renders`: {compositionId, format, resolution} → render
- `GET /renders/{id}`: Progress, then url + playbackUrl

## /videos

A hosted, playable URL for any asset or render. Embed it anywhere.

- `POST /videos`: Publish an asset or render → playbackUrl, embedUrl
- `GET /videos/{id}`: Playback URLs, thumbnail, captions
- `GET /videos/{id}/analytics`: Views and watch time

## /account

Metered usage and webhooks.

- `GET /account`: Which organization a key belongs to
- `GET /usage`: Usage per meter for a date range
- `POST /webhooks/endpoints`: Get called when renders and generations finish

# Models (`model` on POST /generations, billed at the provider's price, 0% markup)

- `bytedance/seedance-2.5` (video, best quality, video edit + extend, up to 30 s; ≈ $0.569/s at 1080p 16:9): $11.7 per 1M tokens
- `bytedance/seedance-2.0` (video, up to 4K; ≈ $1.497/s at 4k 16:9): $7.7 per 1M tokens
- `bytedance/seedance-2.0-fast` (video, quicker, up to 720p; ≈ $0.121/s at 720p 16:9): $5.6 per 1M tokens
- `bytedance/seedance-2.0-mini` (video, cheapest, up to 720p; ≈ $0.076/s at 720p 16:9): $3.5 per 1M tokens
- `openai/gpt-image` (image, reference-image aware): $0.04 per image
- `elevenlabs/sound-effects` (audio, prompt → SFX): $0.002 per second
- `elevenlabs/tts` (speech, voices + cloning): $0.12 per 1k chars
- `assemblyai/universal` (transcription, word-level timings): $0.004 per audio minute

# bytedance/seedance on POST /generations

Every BytePlus parameter is supported. Billing: the tokens BytePlus reports for the task (`usage.completionTokens` on the generation) × the model's price per 1M tokens, 0% markup. Tokens ≈ width × height × 24 × seconds / 1024 of the output. Tasks with a reference video bill at BytePlus' video-input token price.

- `prompt` (string): What to generate. Put dialogue in double quotes for spoken audio. (content text)
- `resolution` ("480p" | "720p" | "1080p" | "4k"): Output resolution; default 720p. 1080p on 2.5 and 2.0, 4k on 2.0 only. (resolution)
- `ratio` ("16:9" | "4:3" | "1:1" | "3:4" | "9:16" | "21:9" | "adaptive"): Aspect ratio; default adaptive (picked from the prompt or inputs). First-frame, edit and extend tasks on 2.5 accept only adaptive. (ratio)
- `duration` (integer): Seconds: 4–30 on 2.5, 4–15 on 2.0 models, or -1 to let the model choose. (duration)
- `generateAudio` (boolean): Synchronised voice, effects and music; default true. Mono. (generate_audio)
- `inputs` (Array<{role, assetId}>): Media to condition on, by asset id. role: first_frame, last_frame (image-to-video), or reference_image (2.5: up to 30, 2.0: up to 9), reference_video, reference_audio (omni reference). Frame roles and reference roles cannot be mixed. 2.0 needs an image or video beside reference_audio. (content image_url / video_url / audio_url + role)
- `draft` (boolean): 2.5 only: a cheap 480p draft to check shots and motion before the final. (draft)
- `draftId` (string): 2.5 only: render the final video from a draft generation's id. (content draft_task)
- `returnLastFrame` (boolean): Also save the last frame as an image asset, to chain clips with first_frame. (return_last_frame)
- `outputFormat` ("mp4" | "mov"): mov keeps more colour precision for grading and keying; default mp4. (output_format)
- `watermark` (boolean): Burn in an "AI Generated" mark; default false. (watermark)
- `expiresAfterSeconds` (integer): Give up if not finished in time: 3600–259200, default 172800. (execution_expires_after)
- `providerOptions` (object): Any other BytePlus task field, sent as-is, so new parameters work on day one.

- `bytedance/seedance-2.5`: $11.7 per 1M tokens; 480p/720p/1080p; 4–30 s; up to 30 reference images; draft mode
- `bytedance/seedance-2.0`: $7.7 per 1M tokens; 480p/720p/1080p/4k; 4–15 s; up to 9 reference images
- `bytedance/seedance-2.0-fast`: $5.6 per 1M tokens; 480p/720p; 4–15 s; up to 9 reference images
- `bytedance/seedance-2.0-mini`: $3.5 per 1M tokens; 480p/720p; 4–15 s; up to 9 reference images

Output sizes (width×height), Seedance 2.0 series; 2.5 differs only at 480p 16:9 (854×480) and 9:16 (480×854):

- 480p: 16:9 864×496, 4:3 752×560, 1:1 640×640, 3:4 560×752, 9:16 496×864, 21:9 992×432
- 720p: 16:9 1280×720, 4:3 1112×834, 1:1 960×960, 3:4 834×1112, 9:16 720×1280, 21:9 1470×630
- 1080p: 16:9 1920×1080, 4:3 1664×1248, 1:1 1440×1440, 3:4 1248×1664, 9:16 1080×1920, 21:9 2206×946
- 4k: 16:9 3840×2160, 4:3 3326×2494, 1:1 2880×2880, 3:4 2494×3326, 9:16 2160×3840, 21:9 4398×1886

# Infrastructure prices

- Render / composite, up to 1080p: $0.03 per output minute
- Render / composite, 4K: $0.12 per output minute
- Playback delivery (HLS + player): $0.0005 per minute watched
- Asset storage: $0.02 per GB-month
- Transcription + word timings: $0.004 per audio minute
- Studio voice enhancement: $0.01 per audio minute

# Limits

- Max asset size: 50 GB
- Max render length: 4 h
- Max output resolution: 3840×2160 @ 60 fps
- Concurrent renders (default): 20 per organization, raise on request
- Generated video length: 4–30 s (Seedance 2.5), 4–15 s (2.0)
- Rate limit: 100 req/s per key
- Minimum spend: none, pay per use
