Lumen5 Video Creation API

openapi: 3.2.0
info:
  title: Lumen5 Video Creation API
  version: 1.0.0
  description: 'Create Lumen5 videos from your content. Authenticate with an API key or an OAuth token as `Authorization: Bearer …`; every call names the workspace it acts in.'
tags:
- name: Video Creation
paths:
  /api/v1/video-creation/blueprints/:
    get:
      operationId: v1_video_creation_blueprints_list
      description: The workspace's blueprints.
      parameters:
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - in: query
        name: search
        schema:
          type: string
        description: Keywords to narrow the list by.
      - in: query
        name: workspace
        schema:
          type: string
        description: A `ws_` id from /workspaces/.
        required: true
      tags:
      - Video Creation
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedBlueprintListingList'
          description: ''
      summary: V1 video creation blueprints list
      x-summary-source: derived
  /api/v1/video-creation/brand-kits/:
    get:
      operationId: v1_video_creation_brand_kits_list
      description: The workspace's brand kits.
      parameters:
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - in: query
        name: search
        schema:
          type: string
        description: Keywords to narrow the list by.
      - in: query
        name: workspace
        schema:
          type: string
        description: A `ws_` id from /workspaces/.
        required: true
      tags:
      - Video Creation
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedReferenceListingList'
          description: ''
      summary: V1 video creation brand kits list
      x-summary-source: derived
  /api/v1/video-creation/projects/:
    get:
      operationId: v1_video_creation_projects_list
      description: Projects in the workspace the caller can put videos in.
      parameters:
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - in: query
        name: search
        schema:
          type: string
        description: Keywords to narrow the list by.
      - in: query
        name: workspace
        schema:
          type: string
        description: A `ws_` id from /workspaces/.
        required: true
      tags:
      - Video Creation
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedReferenceListingList'
          description: ''
      summary: V1 video creation projects list
      x-summary-source: derived
  /api/v1/video-creation/recipes/:
    get:
      operationId: v1_video_creation_recipes_list
      description: The kinds of video a request can ask for.
      parameters:
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - in: query
        name: search
        schema:
          type: string
        description: Keywords to narrow the list by.
      - in: query
        name: workspace
        schema:
          type: string
        description: A `ws_` id from /workspaces/.
        required: true
      tags:
      - Video Creation
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedRecipeListingList'
          description: ''
      summary: V1 video creation recipes list
      x-summary-source: derived
  /api/v1/video-creation/requests/:
    get:
      operationId: v1_video_creation_requests_list
      parameters:
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - in: query
        name: status
        schema:
          type: string
          enum:
          - completed
          - failed
          - running
      - in: query
        name: workspace
        schema:
          type: string
        description: A `ws_` id from /workspaces/.
        required: true
      tags:
      - Video Creation
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedVideoCreationRequestList'
          description: ''
      summary: V1 video creation requests list
      x-summary-source: derived
    post:
      operationId: v1_video_creation_requests_create
      parameters:
      - in: header
        name: Idempotency-Key
        schema:
          type: string
        description: Retrying with the same key returns the original request instead of making another video.
      tags:
      - Video Creation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoCreationRequestBodyRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/VideoCreationRequestBodyRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/VideoCreationRequestBodyRequest'
        required: true
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoCreationRequest'
          description: ''
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoCreationRequest'
          description: A retry of an earlier request.
        '409':
          description: The idempotency key was already used with a different body.
      summary: V1 video creation requests create
      x-summary-source: derived
  /api/v1/video-creation/requests/{request_id}/:
    get:
      operationId: v1_video_creation_requests_retrieve
      parameters:
      - in: path
        name: request_id
        schema:
          type: string
          pattern: ^[^/]+$
        required: true
      tags:
      - Video Creation
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoCreationRequest'
          description: ''
      summary: V1 video creation requests retrieve
      x-summary-source: derived
  /api/v1/video-creation/resolve/:
    post:
      operationId: v1_video_creation_resolve_create
      description: Validates a request body and shows what it would store, without creating anything.
      tags:
      - Video Creation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoCreationRequestBodyRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/VideoCreationRequestBodyRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/VideoCreationRequestBodyRequest'
        required: true
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvedVideoCreationRequest'
          description: ''
      summary: V1 video creation resolve create
      x-summary-source: derived
  /api/v1/video-creation/templates/:
    get:
      operationId: v1_video_creation_templates_list
      description: Templates the workspace can use.
      parameters:
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - in: query
        name: search
        schema:
          type: string
        description: Keywords to narrow the list by.
      - in: query
        name: workspace
        schema:
          type: string
        description: A `ws_` id from /workspaces/.
        required: true
      tags:
      - Video Creation
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTemplateListingList'
          description: ''
      summary: V1 video creation templates list
      x-summary-source: derived
  /api/v1/video-creation/voices/:
    get:
      operationId: v1_video_creation_voices_list
      description: AI voices the workspace can use.
      parameters:
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - in: query
        name: search
        schema:
          type: string
        description: Keywords to narrow the list by.
      - in: query
        name: workspace
        schema:
          type: string
        description: A `ws_` id from /workspaces/.
        required: true
      tags:
      - Video Creation
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedVoiceListingList'
          description: ''
      summary: V1 video creation voices list
      x-summary-source: derived
  /api/v1/video-creation/webhook-endpoints/:
    get:
      operationId: v1_video_creation_webhook_endpoints_list
      parameters:
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      tags:
      - Video Creation
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedWebhookEndpointList'
          description: ''
      summary: V1 video creation webhook endpoints list
      x-summary-source: derived
    post:
      operationId: v1_video_creation_webhook_endpoints_create
      tags:
      - Video Creation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/WebhookEndpointRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/WebhookEndpointRequest'
        required: true
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointSecret'
          description: ''
      summary: V1 video creation webhook endpoints create
      x-summary-source: derived
  /api/v1/video-creation/webhook-endpoints/{endpoint_id}/:
    delete:
      operationId: v1_video_creation_webhook_endpoints_destroy
      parameters:
      - in: path
        name: endpoint_id
        schema:
          type: string
          pattern: ^[^/]+$
        required: true
      tags:
      - Video Creation
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '204':
          description: No response body
      summary: V1 video creation webhook endpoints destroy
      x-summary-source: derived
  /api/v1/video-creation/webhook-endpoints/{endpoint_id}/rotate-secret/:
    post:
      operationId: v1_video_creation_webhook_endpoints_rotate_secret_create
      description: Issues a new signing secret. The old one keeps signing deliveries for a day, so nothing drops.
      parameters:
      - in: path
        name: endpoint_id
        schema:
          type: string
          pattern: ^[^/]+$
        required: true
      tags:
      - Video Creation
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointSecret'
          description: ''
      summary: V1 video creation webhook endpoints rotate secret create
      x-summary-source: derived
  /api/v1/video-creation/workspaces/:
    get:
      operationId: v1_video_creation_workspaces_list
      description: The workspaces the caller can create videos in.
      parameters:
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      tags:
      - Video Creation
      security:
      - ApiKey: []
      - OAuth2: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedReferenceListingList'
          description: ''
      summary: V1 video creation workspaces list
      x-summary-source: derived
components:
  schemas:
    PaginatedWebhookEndpointList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEndpoint'
    TemplateListing:
      type: object
      description: The fields every listing shares; each kind adds what helps choose between options.
      properties:
        id:
          type: string
        label:
          type: string
        description:
          type:
          - string
          - 'null'
        aspect_ratios:
          type: array
          items:
            $ref: '#/components/schemas/AspectRatio'
        preview_url:
          type:
          - string
          - 'null'
          format: uri
      required:
      - aspect_ratios
      - description
      - id
      - label
      - preview_url
    InputContent:
      type: object
      description: What the video is made from. Read from and written to the request's own columns.
      properties:
        script:
          type:
          - string
          - 'null'
          description: Narration for the video, used word for word. Give script or text, not both; leave both out to make the video from instructions alone.
        text:
          type:
          - string
          - 'null'
          description: Source material (an article, notes, a brief) to write the script from. Give script or text, not both; leave both out to make the video from instructions alone.
    AspectRatio:
      enum:
      - landscape
      - square
      - vertical
      - fourfive
      type: string
      description: '* `landscape` - Landscape

        * `square` - Square

        * `vertical` - Vertical

        * `fourfive` - Fourfive'
    PaginatedVideoCreationRequestList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/VideoCreationRequest'
    InputContentRequest:
      type: object
      description: What the video is made from. Read from and written to the request's own columns.
      properties:
        script:
          type:
          - string
          - 'null'
          minLength: 1
          description: Narration for the video, used word for word. Give script or text, not both; leave both out to make the video from instructions alone.
        text:
          type:
          - string
          - 'null'
          minLength: 1
          description: Source material (an article, notes, a brief) to write the script from. Give script or text, not both; leave both out to make the video from instructions alone.
    WebhookEndpointSecret:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        url:
          type: string
          format: uri
          maxLength: 500
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventsEnum'
        created_at:
          type: string
          format: date-time
          readOnly: true
        secret:
          type: string
          readOnly: true
          description: Signs deliveries. Returned only once.
      required:
      - created_at
      - events
      - id
      - secret
      - url
    PaginatedReferenceListingList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/ReferenceListing'
    PaginatedVoiceListingList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/VoiceListing'
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        url:
          type: string
          format: uri
          maxLength: 500
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventsEnum'
        created_at:
          type: string
          format: date-time
          readOnly: true
      required:
      - created_at
      - events
      - id
      - url
    EventsEnum:
      enum:
      - request.completed
      - request.failed
      type: string
      description: '* `request.completed` - Request Completed

        * `request.failed` - Request Failed'
    RecipeListing:
      type: object
      description: The fields every listing shares; each kind adds what helps choose between options.
      properties:
        id:
          type: string
        label:
          type: string
        description:
          type: string
      required:
      - description
      - id
      - label
    VideoCreationRequest:
      type: object
      description: 'A request as stored: every input and setting, with null for what was left out.'
      properties:
        id:
          type: string
          readOnly: true
        status:
          allOf:
          - $ref: '#/components/schemas/StatusEnum'
          readOnly: true
        workspace:
          type: string
          readOnly: true
        input_content:
          allOf:
          - $ref: '#/components/schemas/InputContent'
          readOnly: true
        output_settings:
          allOf:
          - $ref: '#/components/schemas/OutputSettings'
          readOnly: true
        instructions:
          type:
          - string
          - 'null'
          readOnly: true
        video_url:
          type:
          - string
          - 'null'
          readOnly: true
        share_page_url:
          type:
          - string
          - 'null'
          readOnly: true
        embed_html:
          type:
          - string
          - 'null'
          readOnly: true
        error:
          type:
          - string
          - 'null'
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        finished_at:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
      required:
      - created_at
      - embed_html
      - error
      - finished_at
      - id
      - input_content
      - instructions
      - output_settings
      - share_page_url
      - status
      - video_url
      - workspace
    PaginatedTemplateListingList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/TemplateListing'
    PaginatedBlueprintListingList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/BlueprintListing'
    ResolvedVideoCreationRequest:
      type: object
      description: 'A request as stored: every input and setting, with null for what was left out.'
      properties:
        workspace:
          type: string
          readOnly: true
        input_content:
          allOf:
          - $ref: '#/components/schemas/InputContent'
          readOnly: true
        output_settings:
          allOf:
          - $ref: '#/components/schemas/OutputSettings'
          readOnly: true
        instructions:
          type:
          - string
          - 'null'
          readOnly: true
      required:
      - input_content
      - instructions
      - output_settings
      - workspace
    StatusEnum:
      enum:
      - running
      - completed
      - failed
      type: string
      description: '* `running` - Running

        * `completed` - Completed

        * `failed` - Failed'
    OutputSettings:
      type: object
      description: How the video should look. Anything left out is null, and the agent chooses it.
      properties:
        blueprint:
          type:
          - string
          - 'null'
          description: A `bp_` id from /blueprints/. A blueprint is a whole house style, so it can't be combined with template, voice, recipe, brand_kit, aspect_ratio or target_duration_seconds; video_name and project can still be set.
        template:
          type:
          - string
          - 'null'
          description: A `tpl_` id from /templates/.
        voice:
          type:
          - string
          - 'null'
          description: A `voice_` id from /voices/.
        recipe:
          type:
          - string
          - 'null'
          description: An id from /recipes/.
        brand_kit:
          type:
          - string
          - 'null'
          description: A `bk_` id from /brand-kits/.
        aspect_ratio:
          allOf:
          - $ref: '#/components/schemas/AspectRatio'
          description: 'The video''s shape.


            * `landscape` - Landscape

            * `square` - Square

            * `vertical` - Vertical

            * `fourfive` - Fourfive'
        target_duration_seconds:
          type:
          - integer
          - 'null'
          maximum: 600
          minimum: 5
          description: Roughly how long the video should be, in seconds. Only applies when Lumen5 writes the script; a `script` fixes the length, so this is ignored alongside one.
        video_name:
          type:
          - string
          - 'null'
          description: What to call the video in Lumen5. At most 150 characters.
          maxLength: 150
        project:
          type:
          - string
          - 'null'
          description: 'A `proj_` id from /projects/: the project in the workspace to put the video in. Left out, it goes to All videos, or for an editor, their most recent project.'
    ReferenceListing:
      type: object
      description: The fields every listing shares; each kind adds what helps choose between options.
      properties:
        id:
          type: string
        label:
          type: string
      required:
      - id
      - label
    VoiceListing:
      type: object
      description: The fields every listing shares; each kind adds what helps choose between options.
      properties:
        id:
          type: string
        label:
          type: string
        attributes:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        preview_url:
          type:
          - string
          - 'null'
          format: uri
        is_paid:
          type: boolean
      required:
      - attributes
      - id
      - is_paid
      - label
      - preview_url
    BlueprintListing:
      type: object
      description: The fields every listing shares; each kind adds what helps choose between options.
      properties:
        id:
          type: string
        label:
          type: string
        description:
          type:
          - string
          - 'null'
        aspect_ratio:
          $ref: '#/components/schemas/AspectRatio'
      required:
      - aspect_ratio
      - description
      - id
      - label
    VideoCreationRequestBodyRequest:
      type: object
      description: What a caller asks for. Validates straight onto the request's columns.
      properties:
        workspace:
          type: string
          minLength: 1
          description: A `ws_` id from /workspaces/.
        input_content:
          $ref: '#/components/schemas/InputContentRequest'
        output_settings:
          $ref: '#/components/schemas/OutputSettingsRequest'
        instructions:
          type: string
          default: ''
          description: Anything else the video should do, in plain language. Enough on its own when there is no script or text.
      required:
      - workspace
    PaginatedRecipeListingList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/RecipeListing'
    WebhookEndpointRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
          minLength: 1
          maxLength: 500
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventsEnum'
      required:
      - events
      - url
    OutputSettingsRequest:
      type: object
      description: How the video should look. Anything left out is null, and the agent chooses it.
      properties:
        blueprint:
          type:
          - string
          - 'null'
          description: A `bp_` id from /blueprints/. A blueprint is a whole house style, so it can't be combined with template, voice, recipe, brand_kit, aspect_ratio or target_duration_seconds; video_name and project can still be set.
        template:
          type:
          - string
          - 'null'
          description: A `tpl_` id from /templates/.
        voice:
          type:
          - string
          - 'null'
          description: A `voice_` id from /voices/.
        recipe:
          type:
          - string
          - 'null'
          minLength: 1
          description: An id from /recipes/.
        brand_kit:
          type:
          - string
          - 'null'
          description: A `bk_` id from /brand-kits/.
        aspect_ratio:
          allOf:
          - $ref: '#/components/schemas/AspectRatio'
          description: 'The video''s shape.


            * `landscape` - Landscape

            * `square` - Square

            * `vertical` - Vertical

            * `fourfive` - Fourfive'
        target_duration_seconds:
          type:
          - integer
          - 'null'
          maximum: 600
          minimum: 5
          description: Roughly how long the video should be, in seconds. Only applies when Lumen5 writes the script; a `script` fixes the length, so this is ignored alongside one.
        video_name:
          type:
          - string
          - 'null'
          minLength: 1
          description: What to call the video in Lumen5. At most 150 characters.
          maxLength: 150
        project:
          type:
          - string
          - 'null'
          description: 'A `proj_` id from /projects/: the project in the workspace to put the video in. Left out, it goes to All videos, or for an editor, their most recent project.'
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: An API key (`lm5_sk_…`) created in Lumen5, with the scopes it was given.
    OAuth2:
      type: http
      scheme: bearer
      description: An OAuth 2.0 access token, with the scopes the user consented to.