VidPlate Render presets API

openapi: 3.2.0
info:
  title: VidPlate Render presets API
  version: v1
  summary: Render video and images from your own templates, on your own machines.
  description: 'Server-to-server only: send your secret key as "Authorization: Bearer vpk_live_...". Requests from a browser are refused, and a secret key must never be put in a web page or an app.


    Every response carries X-Request-Id. Errors use one shape (see the Error schema) with stable codes. Lists use cursor pagination: pass next_cursor as starting_after.


    Rate limits are per key and per workspace, with RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers, and Retry-After on 429.


    Renders run on your workspace''s own Browser Nodes (the render-nodes endpoints) and are not charged per render; paid API plans have a daily render limit and a monthly video-minutes allowance (429 quota_exceeded and 429 video_minutes_exceeded); Studio Pro has 10,000 static outputs and 2,000 video minutes a calendar month (429 static_outputs_exceeded and 429 video_minutes_exceeded) plus a daily safety limit (429 quota_exceeded); the Sandbox has one-off totals for its whole trial (402 sandbox_allowance_used). Webhooks are signed (VidPlate-Signature: t=..., v1=HMAC-SHA256 of "t.body") and carry IDs and statuses only.'
servers:
- url: https://api.vidplate.app/v1
  description: VidPlate API
- url: https://vidplate.app/api/v1
  description: Legacy base URL. It keeps working for existing integrations.
security:
- apiKey: []
tags:
- name: Render presets
  description: '3D render presets: named Volt or Prism settings, made in the developer console, that a render names by code.'
paths:
  /render-presets:
    get:
      operationId: listRenderPresets
      tags:
      - Render presets
      summary: List 3D render presets
      description: 'Your workspace''s 3D render presets: named settings for the Volt (real-time) or Prism (the most realistic light, shadows and reflections) renderer, made in the developer console, after the eight standard presets every workspace has (volt-low, volt-medium, volt-high, volt-extreme, prism-low, prism-medium, prism-high and prism-extreme, built_in true, listed first). Name one by its code on a render (render_preset) to render the templates'' 3D content with those settings. Read only.'
      security:
      - apiKey: []
      x-required-scopes:
      - renders:read
      responses:
        '200':
          description: Every preset, by name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderPresetList'
              example:
                object: list
                data:
                - object: render_preset
                  id: rpr_std_prism-high
                  code: prism-high
                  name: Prism High
                  renderer: prism
                  built_in: true
                  description: 'Prism High: clean, finished realistic light, for final videos.'
                  settings:
                    samples: 64
                    light_bounces: 6
                    trace_resolution: 1
                    output_reconstruction: balanced
                    denoiser: final
                    adaptive_sampling: true
                    noise_threshold: 0.025
                    secondary_ray_detail: balanced
                  created_at: null
                  updated_at: null
                - object: render_preset
                  id: rpr_6729c0a1b2c3d4e5f6a7b9c1
                  code: prism-hero-4k
                  name: Prism hero 4K
                  renderer: prism
                  built_in: false
                  description: null
                  settings:
                    quality: ultra
                    samples: 96
                    light_bounces: 6
                    trace_resolution: 0.5
                    output_reconstruction: 4k
                    denoiser: final
                    adaptive_sampling: true
                    noise_threshold: 0.018
                    bloom: true
                    bloom_intensity: 80
                  created_at: '2026-11-02T08:58:00.000Z'
                  updated_at: '2026-11-02T09:00:00.000Z'
                has_more: false
                next_cursor: null
        '401':
          description: 'Error. Codes: invalid_api_key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: authentication_failed
                  code: invalid_api_key
                  message: '...'
                  request_id: req_0123456789abcdef01234567
        '403':
          description: 'Error. Codes: missing_scope, plan_not_eligible.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: permission_denied
                  code: missing_scope
                  message: '...'
                  request_id: req_0123456789abcdef01234567
        '429':
          description: 'Error. Codes: too_many_requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: rate_limited
                  code: too_many_requests
                  message: '...'
                  request_id: req_0123456789abcdef01234567
        '500':
          description: 'Error. Codes: internal_error.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: api_error
                  code: internal_error
                  message: '...'
                  request_id: req_0123456789abcdef01234567
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - type
          - code
          - message
          - request_id
          properties:
            type:
              enum:
              - invalid_request
              - payment_required
              - authentication_failed
              - permission_denied
              - not_found
              - conflict
              - unprocessable
              - rate_limited
              - api_error
              - service_unavailable
            code:
              type: string
              description: Stable, documented code.
            message:
              type: string
            param:
              type: string
              description: The request field the error is about, when there is one.
            errors:
              type: array
              description: Every problem found (schema_validation_failed).
              items:
                type: object
                properties:
                  param:
                    type: string
                  code:
                    type: string
                  message:
                    type: string
            request_id:
              type: string
              description: Quote this when asking for help.
    RenderPresetList:
      type: object
      properties:
        object:
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/RenderPreset'
        has_more:
          type: boolean
        next_cursor:
          type:
          - string
          - 'null'
    RenderPreset:
      type: object
      description: A 3D render preset. settings holds only what the preset sets; anything left out keeps the template's own value.
      properties:
        object:
          const: render_preset
        id:
          type: string
          description: 'rpr_... (standard presets: rpr_std_<code>).'
        built_in:
          type: boolean
          description: true for the eight standard presets every workspace has. They are read only, listed first, and their codes are reserved.
        description:
          type:
          - string
          - 'null'
          description: What a standard preset is for. null for your own presets.
        code:
          type: string
          description: 'What a render names: render_preset: "<code>". Unique in the workspace.'
        name:
          type: string
        renderer:
          enum:
          - volt
          - prism
          description: 'volt: real-time, fast. prism: the most realistic light, shadows and reflections, and much slower to render.'
        settings:
          type: object
          additionalProperties: false
          properties:
            quality:
              enum:
              - low
              - medium
              - high
              - ultra
              description: 'Detail budget for geometry, shadows, reflections and bloom: low, medium, high or ultra.'
            exposure_ev:
              type: number
              minimum: -5
              maximum: 5
              description: Scene brightness in stops, -5 to 5.
            direct_lights:
              type: boolean
              description: Directional, point and scene lights.
            cast_shadows:
              type: boolean
              description: Objects cast shadows.
            contact_shadows:
              type: boolean
              description: Fine grounding shadows where objects meet.
            ambient_occlusion:
              type: boolean
              description: Soft shading where objects are close together.
            emissive_materials:
              type: boolean
              description: Self-lit material colour.
            ray_traced_shadows:
              type: boolean
              description: Volt only. Sharper, more accurate shadows. Slower to render.
            samples:
              type: integer
              minimum: 1
              maximum: 256
              description: Prism only. Samples per frame, 1 to 256. More samples mean less noise and longer renders.
            light_bounces:
              type: integer
              minimum: 1
              maximum: 8
              description: Prism only. How many times light bounces, 1 to 8.
            trace_resolution:
              enum:
              - 0.25
              - 0.5
              - 0.67
              - 0.75
              - 1
              description: 'Prism only. Share of the output size that is traced before reconstruction: 0.25, 0.5, 0.67, 0.75 or 1 (native).'
            output_reconstruction:
              enum:
              - balanced
              - 4k
              description: Prism only. balanced, or 4k for extra detail on 4K outputs.
            denoiser:
              enum:
              - interactive
              - final
              - compact
              - 'off'
              description: 'Prism only. interactive: fast clean-up. final: the cleanest result, takes a little longer after sampling. compact: a lighter final clean-up. off: no clean-up.'
            automatic_device_quality:
              type: boolean
              description: Prism only. Lets each render node pick resolution, samples and bounces to suit its speed.
            low_memory_tiled_final:
              type: boolean
              description: Prism only. Renders large frames in tiles so render nodes with less graphics memory can make them.
            secondary_ray_detail:
              enum:
              - full
              - balanced
              - fast
              description: 'Prism only. Texture detail in reflections and bounced light: full, balanced or fast.'
            adaptive_sampling:
              type: boolean
              description: Prism only. Stops sampling pixels that are already clean and spends the time on noisy areas.
            many_light_reservoirs:
              type: boolean
              description: Prism only. Cleaner results in scenes with eight or more lights.
            noise_threshold:
              type: number
              minimum: 0.0025
              maximum: 0.25
              description: Prism only. With adaptive sampling, how much noise a pixel may keep, 0.0025 to 0.25. Lower is cleaner and slower.
            cached_bounce_lighting:
              type: boolean
              description: Colour bouncing between nearby objects.
            environment_colour:
              type: string
              pattern: ^#[0-9A-Fa-f]{6}$
              description: A solid world colour (#RRGGBB) that lights and reflects in the scene. Replaces the template's world. Cannot be combined with environment_map_url.
            environment_map_url:
              type: string
              format: uri
              description: An https link to an equirectangular .hdr or .exr image to light and reflect the scene. Your render nodes download it, so it must allow cross-origin requests.
            world_lighting:
              type: boolean
              description: The world lights the scene.
            environment_shadows:
              type: boolean
              description: Objects shade each other from bright parts of the world.
            dynamic_bounce_lighting:
              type: boolean
              description: One light adds a soft colour bounce. Best for still, solid scenes.
            lighting_brightness:
              type: number
              minimum: 0
              maximum: 1000
              description: Brightness of the world light in percent, 0 to 1,000 (100 is normal).
            reflections:
              type: boolean
              description: Scene and world reflections.
            reflection_strength:
              type: number
              minimum: 0
              maximum: 1000
              description: Strength of reflections in percent, 0 to 1,000 (100 is normal).
            bloom:
              type: boolean
              description: Glow around bright highlights.
            bloom_intensity:
              type: number
              minimum: 0
              maximum: 1000
              description: Glow strength in percent, 0 to 1,000 (100 is normal).
            anamorphic_streaks:
              type: boolean
              description: Horizontal lens streaks from bright highlights.
            streak_intensity:
              type: number
              minimum: 0
              maximum: 1000
              description: Streak strength in percent, 0 to 1,000 (100 is normal).
            chromatic_aberration:
              type: boolean
              description: Slight colour fringing in the glow.
            colour_separation:
              type: number
              minimum: 0
              maximum: 1000
              description: Colour fringing distance in percent, 0 to 1,000 (100 is normal).
            cinematic_post_processing:
              type: boolean
              description: Smoother object edges and a cinematic finish.
            antialiasing_strength:
              type: number
              minimum: 0
              maximum: 100
              description: Edge smoothing in percent, 0 to 100.
            vignette:
              type: number
              minimum: 0
              maximum: 1000
              description: Darkening of the frame edges in percent, 0 to 1,000 (100 is normal).
            height_fog:
              type: boolean
              description: Distance haze that gathers low in the scene.
            fog_colour:
              type: string
              pattern: ^#[0-9A-Fa-f]{6}$
              description: Fog colour (#RRGGBB). Without it the fog matches the scene lighting.
            fog_density:
              type: number
              minimum: 0
              maximum: 1000
              description: Fog density in percent, 0 to 1,000 (100 is normal).
            progressive_final_lighting:
              type: boolean
              description: Extra lighting samples and full-resolution fog in every exported frame.
        created_at:
          type:
          - string
          - 'null'
        updated_at:
          type:
          - string
          - 'null'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: vpk_live_...
      description: 'Workspace keys, created by workspace admins in VidPlate under Admin, then API. Scopes: templates:read (List templates, versions and their input schemas.); uploads:write (Upload images and video to use in renders.); renders:write (Create, cancel and retry renders.); renders:read (Check render status and download outputs.); webhooks:manage (Register and change webhook endpoints.); assets:read (Use Asset Library files as render inputs.); ai:spend (Allow renders that use AI voiceover or AI Recipes. These spend your AI credits.); render_nodes:read (See whether your render nodes are online, busy or offline, and what they can render.); storage_destinations:manage (Add, change, test and delete your own buckets that outputs are delivered to (Growth and above).)'