Creatomate Renders API

openapi: 3.0.1
info:
  title: Creatomate Renders API
  description: REST API for the Creatomate media-automation platform. Generate videos and images at scale by applying per-element modifications to reusable templates. Renders run asynchronously; callers poll for status or receive a webhook when each render reaches a terminal state. All requests are authenticated with a project API key sent as a Bearer token.
  termsOfService: https://creatomate.com/legal/terms
  contact:
    name: Creatomate Support
    url: https://creatomate.com/contact
  version: '1.0'
servers:
- url: https://api.creatomate.com/v1
  description: Creatomate REST API v1
security:
- bearerAuth: []
tags:
- name: Renders
  description: Create renders and check their status.
paths:
  /renders:
    post:
      operationId: createRender
      tags:
      - Renders
      summary: Create one or more renders
      description: Starts one or more renders. Provide a `template_id` or a `source` to create a single render, or one or more `tags` to render every template carrying those tags. The response is returned immediately with each queued render in the `planned` state; the output is produced asynchronously.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRenderRequest'
            examples:
              byTemplate:
                summary: Render a single template with modifications
                value:
                  template_id: 5b6a3c7e-2f1d-4a8b-9c0e-1d2f3a4b5c6d
                  modifications:
                    Text-1: Hi! Thanks for trying out Creatomate!
                    Video: https://creatomate-static.s3.amazonaws.com/demo/video5.mp4
                  output_format: mp4
                  webhook_url: https://example.com/webhooks/creatomate
                  metadata: order-1234
      responses:
        '202':
          description: Accepted. The renders have been queued. Returns an array of Render objects in their initial state.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Render'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    get:
      operationId: listRenders
      tags:
      - Renders
      summary: List renders
      description: Returns renders belonging to the project, most recent first. Supports filtering by template and pagination.
      parameters:
      - name: template_id
        in: query
        required: false
        description: Only return renders produced from this template.
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        required: false
        description: Maximum number of renders to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      responses:
        '200':
          description: An array of Render objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Render'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /renders/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: The unique identifier of the render.
      schema:
        type: string
        format: uuid
    get:
      operationId: getRender
      tags:
      - Renders
      summary: Get the status of a render
      description: Returns the current state of a single render, including its `status` and, once complete, the `url` of the produced file.
      responses:
        '200':
          description: The requested Render object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Render'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deleteRender
      tags:
      - Renders
      summary: Delete a render
      description: Deletes a render and its associated output file.
      responses:
        '200':
          description: The render was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Render'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    Unauthorized:
      description: The API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded. Retry after backing off.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request body was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Render:
      type: object
      description: A render job and, once complete, a pointer to its output file.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the render.
        status:
          $ref: '#/components/schemas/RenderStatus'
        error_message:
          type: string
          nullable: true
          description: Present only when status is `failed`; explains the failure.
        url:
          type: string
          format: uri
          nullable: true
          description: URL of the produced file once the render has succeeded.
        snapshot_url:
          type: string
          format: uri
          nullable: true
          description: URL of a still preview image of the output.
        template_id:
          type: string
          format: uuid
          nullable: true
          description: The template this render was produced from, if any.
        template_name:
          type: string
          nullable: true
          description: Name of the source template.
        template_tags:
          type: array
          nullable: true
          description: Tags of the source template.
          items:
            type: string
        output_format:
          type: string
          description: The output file format.
          enum:
          - jpg
          - png
          - gif
          - mp4
        render_scale:
          type: number
          description: The scale applied relative to the template.
        width:
          type: integer
          description: Output width in pixels.
        height:
          type: integer
          description: Output height in pixels.
        frame_rate:
          type: number
          nullable: true
          description: Output frame rate in fps for video output.
        duration:
          type: number
          nullable: true
          description: Output duration in seconds for video output.
        file_size:
          type: integer
          nullable: true
          description: Size of the output file in bytes.
        modifications:
          type: object
          nullable: true
          description: The modifications that were applied to produce this render.
          additionalProperties: true
        metadata:
          type: string
          nullable: true
          description: Caller-supplied metadata echoed back from the create request.
      required:
      - id
      - status
    CreateRenderRequest:
      type: object
      description: Body for POST /renders. Supply exactly one of `template_id`, `source`, or `tags` to select what is rendered.
      properties:
        template_id:
          type: string
          format: uuid
          description: The template to render.
        source:
          type: object
          description: An inline RenderScript source object, used instead of a template_id to render an ad-hoc design.
          additionalProperties: true
        tags:
          type: array
          description: One or more template tags. Every template carrying any of these tags is rendered, allowing batches to be started in one request.
          items:
            type: string
        modifications:
          type: object
          description: Map of element name to replacement value. Keys are the named elements declared in the template (for example `Text-1`, `Video`); values may be strings, numbers, URLs, or nested property objects.
          additionalProperties: true
        output_format:
          type: string
          description: The output file format. Defaults to the template's format.
          enum:
          - jpg
          - png
          - gif
          - mp4
        frame_rate:
          type: number
          description: Frame rate (fps) for video output. Defaults to the template's frame rate.
        render_scale:
          type: number
          description: Scale of the render relative to the template. 1.0 (the default) produces the same dimensions as the template.
          default: 1.0
        max_width:
          type: number
          description: Scales the render so its width never exceeds this value while preserving aspect ratio. Overrides render_scale when set.
        max_height:
          type: number
          description: Scales the render so its height never exceeds this value while preserving aspect ratio. Overrides render_scale when set.
        webhook_url:
          type: string
          format: uri
          description: URL that Creatomate calls with an HTTP POST carrying the Render object once the render succeeds or fails.
        metadata:
          type: string
          description: Arbitrary text stored with the render and echoed back in the Render object and the webhook payload.
      additionalProperties: false
    Error:
      type: object
      description: Error response payload.
      properties:
        hint:
          type: string
          description: Human-readable description of the error.
      additionalProperties: true
    RenderStatus:
      type: string
      description: Lifecycle state of a render. `succeeded` and `failed` are terminal states that trigger the webhook, if configured.
      enum:
      - planned
      - waiting
      - transcribing
      - rendering
      - succeeded
      - failed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Project API key sent as `Authorization: Bearer <API_KEY>`. The key is found in the project settings of the Creatomate dashboard.'