Skip to main content
POST
Create a render
The request body carries one of two shapes, selected by Content-Type. multipart/form-data creates a render directly from character and motion inputs, each supplied as an uploaded file, a URL, or the ID of a saved asset. This form answers 200 and ignores Idempotency-Key. application/json creates a render from a draft prepared by Prepare Render. This form answers 202, requires Idempotency-Key, and is idempotent within the authenticated project or OAuth principal: reusing the same key with the same normalized input returns the original render, while reusing it with different input returns IDEMPOTENCY_KEY_REUSED.
Pricing (1 credit = 0.01):∗∗0.01): **0.01 per character in the render, per second** of the finished video. Only one character is supported per render today, so this is 0.01/second∗∗inpractice—a10−secondrendercosts∗∗0.01/second** in practice — a 10-second render costs **0.10 (10 credits). There is no per-render minimum charge; the amount reserved when the render starts is an estimate based on the requested inputs and is finalized against the actual completed duration once the render finishes. See Pricing and retention.

​
Request parameters — multipart/form-data

If neither the character group nor the motion group is supplied at all, the server substitutes its own preconfigured default character_id/motion_id and renders that instead of rejecting the request. Supplying either group partially — for example a character source with no motion source — is still an error. bg_color is only valid with background_mode=solid.
The default character_id/motion_id are configured per project/environment, not fixed across all of Viggle — two API keys can send an all-empty request and get different results. Don’t rely on this fallback for anything beyond a quick smoke test; always supply an explicit character and motion source in production traffic.

​
Request parameters — application/json (draft-based)

​
Response parameters

multipart/form-data returns 200 OK; the application/json draft form returns 202 Accepted. Both return a Render object, though the 200 response from a direct multipart request only carries information in id, status, progress, and created_at.
links.self mirrors the retired GET /v1/renders/{render_id} and no longer resolves — poll Get Video with the same id instead. links.events and links.download are unaffected.

​
Examples — direct multipart/form-data

​
Examples — draft-based application/json

See Prepare Render for how to obtain draft_id and upload the character/motion media before calling this endpoint in JSON mode.

Authorizations

​
Authorization
string
header
required

Server-side SDK clients use a project API key. Remote MCP clients use an OAuth access token. Never expose a project API key in browser code.

Headers

​
Idempotency-Key
string

Caller-generated stable key, maximum 255 characters. Required by the application/json draft form of POST /v1/renders and ignored by the multipart/form-data form.

Required string length: 1 - 255
​
X-Request-Id
string

Optional caller-supplied correlation ID, up to 128 characters. The service returns the effective value in the response header for tracing and support.

Required string length: 1 - 128
​
X-Viggle-Source
string

Optional source-channel label, up to 128 characters, used to attribute traffic to an SDK, integration, product surface, or internal workflow.

Required string length: 1 - 128

Body

Supply the character as one of image, image_url, or character_id, and the motion as one of motion_video, motion_video_url, or motion_id. If neither group is supplied at all, the server substitutes its own preconfigured default character_id/motion_id and renders that instead of rejecting the request — supplying either group partially (for example a character source with no motion source) is still an error.

​
image
file

Character image uploaded directly. Use exactly one character source among image, image_url, and character_id.

​
image_url
string<uri>

Public URL of a character image that the service can fetch. Use instead of image or character_id.

​
character_id
string

ID of a ready reusable Character owned by the caller. Use instead of uploading or linking a new image.

Minimum string length: 1
​
motion_video
file

Driving video uploaded directly. Use exactly one motion source among motion_video, motion_video_url, and motion_id.

​
motion_video_url
string<uri>

Public URL of a driving video that the service can fetch. Use instead of motion_video or motion_id.

​
motion_id
string

ID of a ready reusable Motion owned by the caller. Use instead of uploading or linking a new driving video.

Minimum string length: 1
​
background_mode
enum<string>
default:original

inpaint is accepted and treated as original. This set is unrelated to RenderOutputOptions.background_mode, which belongs to the draft-based flow.

Available options:
original,
solid,
transparent,
inpaint
​
bg_color
string

Solid background colour as three decimal components, "R,G,B", for example "0,177,64". Valid only with background_mode=solid.

Example:

"0,177,64"

Response

Render accepted from a direct multipart/form-data request. Only id, status, progress, and created_at carry information.

stage, progress, and created_at are null on renders that carry no such information, and links is absent on renders served by the migration proxy. Treat all four as optional when reading.

The resource response exposes the result URLs but does not expose media dimensions, duration, thumbnail URL, or URL expiry metadata. Clients must not infer those fields from this contract.

​
id
string
required

Public Render ID, normally beginning with render_; use it with get, events, and download operations.

Minimum string length: 1
​
status
enum<string>
required

Overall render lifecycle. ready, failed, and cancelled are terminal states.

Available options:
queued,
processing,
ready,
failed,
cancelled
​
stage
enum<string> | null
required

Coarse pipeline phase when one can be mapped to the public vocabulary; null when unavailable or unknown.

Available options:
queued,
preparing,
generating,
finalizing,
ready,
failed,
cancelled,
analyzing,
rendering,
finishing
​
progress
integer | null
required

Best-effort completion percentage from 0 through 100; null when the active pipeline does not report progress.

Required range: 0 <= x <= 100
​
video_url
string<uri> | null
required

Short-lived URL of the completed rendered video; null until the render is ready or when no output was produced.

​
alpha_url
string<uri> | null
required

Short-lived alpha/mask video URL for transparent output; null for non-transparent renders or until ready.

​
created_at
string<date-time> | null
required

ISO 8601 timestamp when the render was created; null when the backing pipeline did not provide it.

​
completed_at
string<date-time> | null
required

ISO 8601 timestamp when the render entered a terminal state; null while it is still active.

​
error
object | null
required

Structured failure details when status is failed; otherwise null.

​
links
object

Navigation paths for this render. May be absent on records served through the migration proxy.