> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodisc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enqueue a render

> Submits a Manim scene for rendering and returns immediately with a `jobId`. The job runs asynchronously on Kodisc's render fleet.

A successful enqueue reserves a minimum number of credits up-front; the final cost is settled (and any unused credits refunded) when the render completes. If your balance is below the minimum reserve, the request fails with `402`.

Track progress by polling [`GET /api/v2/render/{jobId}`](/api-reference/endpoint/get-render) or by configuring a webhook (see [Webhooks](/webhooks)).




## OpenAPI

````yaml POST /api/v2/render
openapi: 3.1.0
info:
  title: Kodisc API
  version: 2.0.0
  description: >
    The Kodisc public API turns [Manim](https://www.manim.community) Python code
    into rendered MP4 videos, thumbnails, and captions.


    Renders run asynchronously: you `POST /api/v2/render` to enqueue a job, get
    back a `jobId`, then either poll `GET /api/v2/render/{jobId}` or receive a
    webhook callback when the job reaches a terminal state.


    All endpoints accept and return JSON. Authenticate every request with an API
    key — see [Authentication](/authentication).
  contact:
    name: Kodisc
    url: https://kodisc.com
servers:
  - url: https://kodisc.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Render
    description: Enqueue Manim render jobs and poll their status.
  - name: Account
    description: Inspect the authenticated key and your credit balance.
paths:
  /api/v2/render:
    post:
      tags:
        - Render
      summary: Enqueue a render job
      description: >
        Submits a Manim scene for rendering and returns immediately with a
        `jobId`. The job runs asynchronously on Kodisc's render fleet.


        A successful enqueue reserves a minimum number of credits up-front; the
        final cost is settled (and any unused credits refunded) when the render
        completes. If your balance is below the minimum reserve, the request
        fails with `402`.


        Track progress by polling [`GET
        /api/v2/render/{jobId}`](/api-reference/endpoint/get-render) or by
        configuring a webhook (see [Webhooks](/webhooks)).
      operationId: enqueueRender
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenderRequest'
            examples:
              minimal:
                summary: Minimal request
                value:
                  code: |
                    from manim import *

                    class HelloKodisc(Scene):
                        def construct(self):
                            self.play(Write(Text("Hello, Kodisc")))
                            self.wait(1)
                  className: HelloKodisc
              full:
                summary: All options
                value:
                  code: |
                    from manim import *

                    class Vertical(Scene):
                        def construct(self):
                            self.play(Write(Text("9:16")))
                            self.wait(1)
                  className: Vertical
                  quality: high
                  aspectRatio: '9:16'
                  fps: 60
                  metadata:
                    projectId: proj_42
                    label: hero-clip
                  webhookUrl: https://example.com/hooks/kodisc
      responses:
        '202':
          description: Job accepted and queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnqueueResponse'
              example:
                jobId: clx9f0a1b0000abcd1234efgh
                status: queued
                endpoint: render
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Not enough credits to start the render.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: insufficient_credits
                message: >-
                  Not enough credits to start a render. Top up at
                  /developer/billing.
components:
  schemas:
    RenderRequest:
      type: object
      required:
        - code
        - className
      additionalProperties: false
      properties:
        code:
          type: string
          minLength: 1
          description: >
            Manim Python source containing your `Scene` subclass. Imports,
            helpers, and the scene class can all live in this string. Maximum
            payload size for the whole request body is roughly 200 KB.
          example: |
            from manim import *

            class HelloKodisc(Scene):
                def construct(self):
                    self.play(Write(Text("Hello, Kodisc")))
                    self.wait(1)
        className:
          type: string
          pattern: ^[A-Za-z_][A-Za-z0-9_]*$
          description: >-
            Name of the `Scene` subclass inside `code` to render. Must be a
            valid Python identifier.
          example: HelloKodisc
        quality:
          $ref: '#/components/schemas/Quality'
        aspectRatio:
          $ref: '#/components/schemas/AspectRatio'
        fps:
          type: integer
          minimum: 1
          description: >-
            Frames per second. Optional — when omitted, Kodisc picks a sensible
            default for the chosen `quality`.
          example: 60
        metadata:
          description: >-
            Arbitrary JSON you want echoed back on the job and webhook payload.
            Useful for correlating with your own IDs.
          example:
            projectId: proj_42
            label: hero-clip
        webhookUrl:
          type:
            - string
            - 'null'
          format: uri
          pattern: ^https://
          description: >
            HTTPS URL to receive a webhook when this specific job reaches a
            terminal state. Overrides the default webhook URL configured on the
            API key. Pass `null` to send no webhook for this job.
          example: https://example.com/hooks/kodisc
    EnqueueResponse:
      type: object
      required:
        - jobId
        - status
        - endpoint
      properties:
        jobId:
          type: string
          description: >-
            Opaque ID for the queued job. Use it to poll status or correlate
            webhook deliveries.
        status:
          type: string
          enum:
            - queued
        endpoint:
          type: string
          enum:
            - render
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Short machine-friendly error code or summary.
        message:
          type: string
          description: Optional human-readable explanation.
    Quality:
      type: string
      enum:
        - low
        - medium
        - high
        - twok
        - fourk
      description: >
        Render quality preset. `low` and `medium` are fastest; `twok` (2K) and
        `fourk` (4K) trade render time and credits for fidelity.
      default: medium
    AspectRatio:
      type: string
      enum:
        - '16:9'
        - '9:16'
      description: >-
        Output aspect ratio. `16:9` is landscape; `9:16` is portrait (e.g. for
        shorts/reels).
      default: '16:9'
  responses:
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidClassName:
              value:
                error: className must be a valid Python identifier
            invalidQuality:
              value:
                error: 'quality must be one of: low, medium, high, twok, fourk'
            invalidWebhookUrl:
              value:
                error: webhookUrl must be an https:// URL
    Unauthorized:
      description: The API key is missing, malformed, revoked, or unknown.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Unauthorized
            message: Invalid or missing API key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: kdsc_live_*
      description: >
        Send your API key in the `Authorization` header as `Bearer
        kdsc_live_<...>`. Generate keys from the [developer
        dashboard](https://kodisc.com/developer/keys). Keys are returned in
        plaintext only once at creation time — store them like a password.

````