openapi: 3.0.1

info:
  title: Shotstack
  version: v1
  description: |
    Shotstack is a video, image and audio editing service that allows for the automated generation of videos, images and audio using JSON and a RESTful API.

    You arrange and configure an edit and POST it to the API which will render your media and provide a file location when complete.

    For more details visit [shotstack.io](https://shotstack.io) or checkout our [getting started](https://shotstack.io/docs/guide/) documentation.

    There are three API's, one for editing and generating assets (Edit API), one for managing hosted assets (Serve API) and one for ingesting and transforming source assets (Ingest API).

    Each API has it's own base URL and collection of endpoints. Each API uses the same set of API keys.

    **[Edit API](#shotstack-edit)** - [https://api.shotstack.io/edit/{version}](#)<br>
    Edit videos, images and audio assets in the cloud using a simple JSON schema and templates.

    **[Serve API](#shotstack-serve)** - [https://api.shotstack.io/serve/{version}](#)<br>
    Inspect and manage the hosting of assets generated by the Edit and Ingest APIs.

    **[Ingest API](#shotstack-ingest)** - [https://api.shotstack.io/ingest/{version}](#)<br>
    Ingest (upload, store and transform) source footage, images, audio and fonts to be used by the Edit API.

    **[Create API](#shotstack-create)** - [https://api.shotstack.io/create/{version}](#)<br>
    Generate images, videos, voice overs and text using built in and third party generative AI providers.

servers:
  - url: https://api.shotstack.io/edit/{version}
    variables:
      version:
        description: >-
          Set the stage to **v1** for production usage without watermarks. Set to **stage** to use the development sandbox.
        enum:
          - v1
          - stage
        default: v1
  - url: https://api.shotstack.io/serve/{version}
    variables:
      version:
        description: >-
          Set the stage to **v1** for production usage. Set to **stage** to use the development sandbox.
        enum:
          - v1
          - stage
        default: v1
  - url: https://api.shotstack.io/ingest/{version}
    variables:
      version:
        description: >-
          Set the stage to **v1** for production usage. Set to **stage** to use the development sandbox.
        enum:
          - v1
          - stage
        default: v1
  - url: https://api.shotstack.io/create/{version}
    variables:
      version:
        description: >-
          Set the stage to **v1** for production usage. Set to **stage** to use the development sandbox.
        enum:
          - v1
          - stage
        default: v1

tags:
  - name: Edit
    description: >-
      The Edit API is used to edit videos, images and audio files in the cloud using a simple to understand JSON schema.
      Compose an edit using tracks, clips and assets and add transitions, filters, overlays and text. Finally send the
      JSON to the Edit API to be rendered.

  - name: Serve
    description: >-
      Assets generated by the Edit API or uploaded via the Ingest API are sent to the Serve API. The Serve API includes
      a simple hosting service with a CDN or you can send assets to third party services like AWS S3 or Mux. The Serve
      API includes endpoints to look up assets, where they are hosted and their status.

  - name: Ingest
    description: >-
      The Ingest API lets you upload and store your source footage and user generated content in close proximity to the
      Edit API. Instead of hosting your own assets or building your own uploader you can use the Ingest API. The Ingest
      API provides endpoints to fetch and upload files and check their status and URLs. All ingested files are available
      directly from an S3 bucket URL or via CDN (Serve API).

  - name: Create
    description: >-
      The Create API generates assets and media files using Generative AI services like text-to-speech and
      text-to-avatar. A native text-to-speech service is included as well as integrations with third party providers.
      Third party services include [HeyGen](https://www.heygen.com/) text-to-avatar, [ElevenLabs](https://elevenlabs.io/)
      text-to-speech and [D-ID](https://www.d-id.com/) text-to-avatar. Assets can be used with the Edit API or
      downloaded and used independently.

paths:
  /render:
    $ref: "./paths/render.yaml"

  /render/{id}:
    $ref: "./paths/renderid.yaml"

  /templates:
    $ref: "./paths/templates.yaml"

  /templates/{id}:
    $ref: "./paths/templatesid.yaml"

  /templates/render:
    $ref: "./paths/templatesrender.yaml"

  /probe/{url}:
    $ref: "./paths/probe.yaml"

  /assets/{id}:
    $ref: "./paths/assetsid.yaml"

  /assets/render/{id}:
    $ref: "./paths/assetsrenderid.yaml"

  /assets:
    $ref: "./paths/assets.yaml"

  /sources:
    $ref: "./paths/sources.yaml"

  /sources/{id}:
    $ref: "./paths/sourcesid.yaml"

  /upload:
    $ref: "./paths/upload.yaml"

  # Because of the way we have our servers set up and Create and Serve share the same endpoint name and how yaml/swagger
  # can't have duplicate keys - we use a temporary path name here /path_alias_createassets and rename it at built time
  # to assets using sed. Better ideas welcomed!
  /path_alias_createassets:
    $ref: "./paths/generateasset.yaml"

  # Using path alias and sed for replacement. See above comment.
  /path_alias_createassets/{id}:
    $ref: "./paths/generateassetid.yaml"

components:
  schemas:
    # Request schemas
    Edit:
      $ref: "./schemas/edit.yaml#/Edit"

    Timeline:
      $ref: "./schemas/timeline.yaml#/Timeline"

    Soundtrack:
      $ref: "./schemas/soundtrack.yaml#/Soundtrack"

    Font:
      $ref: "./schemas/font.yaml#/Font"

    Track:
      $ref: "./schemas/track.yaml#/Track"

    Clip:
      $ref: "./schemas/clip.yaml#/Clip"

    Asset:
      $ref: "./schemas/asset.yaml#/Asset"

    VideoAsset:
      $ref: "./schemas/videoasset.yaml#/VideoAsset"

    ImageAsset:
      $ref: "./schemas/imageasset.yaml#/ImageAsset"

    TitleAsset:
      $ref: "./schemas/titleasset.yaml#/TitleAsset"

    HtmlAsset:
      $ref: "./schemas/htmlasset.yaml#/HtmlAsset"

    AudioAsset:
      $ref: "./schemas/audioasset.yaml#/AudioAsset"

    LumaAsset:
      $ref: "./schemas/lumaasset.yaml#/LumaAsset"

    Transition:
      $ref: "./schemas/transition.yaml#/Transition"

    Offset:
      $ref: "./schemas/offset.yaml#/Offset"

    Crop:
      $ref: "./schemas/crop.yaml#/Crop"

    Transformation:
      $ref: "./schemas/transformation.yaml#/Transformation"

    RotateTransformation:
      $ref: "./schemas/rotatetransformation.yaml#/RotateTransformation"

    SkewTransformation:
      $ref: "./schemas/skewtransformation.yaml#/SkewTransformation"

    FlipTransformation:
      $ref: "./schemas/fliptransformation.yaml#/FlipTransformation"

    MergeField:
      $ref: "./schemas/mergefield.yaml#/MergeField"

    Output:
      $ref: "./schemas/output.yaml#/Output"

    Size:
      $ref: "./schemas/size.yaml#/Size"

    Range:
      $ref: "./schemas/range.yaml#/Range"

    Poster:
      $ref: "./schemas/poster.yaml#/Poster"

    Thumbnail:
      $ref: "./schemas/thumbnail.yaml#/Thumbnail"

    Destinations:
      $ref: "./schemas/destinations.yaml#/Destinations"

    ShotstackDestination:
      $ref: "./schemas/destinations/shotstackDestination.yaml#/ShotstackDestination"

    MuxDestination:
      $ref: "./schemas/destinations/muxDestination.yaml#/MuxDestination"

    MuxDestinationOptions:
      $ref: "./schemas/destinations/muxDestinationOptions.yaml#/MuxDestinationOptions"

    S3Destination:
      $ref: "./schemas/destinations/s3Destination.yaml#/S3Destination"

    S3DestinationOptions:
      $ref: "./schemas/destinations/s3DestinationOptions.yaml#/S3DestinationOptions"

    GoogleCloudStorageDestination:
      $ref: "./schemas/destinations/googleCloudStorageDestination.yaml#/GoogleCloudStorageDestination"

    GoogleCloudStorageDestinationOptions:
      $ref: "./schemas/destinations/googleCloudStorageDestinationOptions.yaml#/GoogleCloudStorageDestinationOptions"

    GoogleDriveDestination:
      $ref: "./schemas/destinations/googleDriveDestination.yaml#/GoogleDriveDestination"

    GoogleDriveDestinationOptions:
      $ref: "./schemas/destinations/googleDriveDestinationOptions.yaml#/GoogleDriveDestinationOptions"

    Template:
      $ref: "./schemas/template.yaml#/Template"

    TemplateRender:
      $ref: "./schemas/templaterender.yaml#/TemplateRender"

    # Ingest schemas
    Source:
      $ref: "./schemas/ingest/source.yaml#/Source"

    Outputs:
      $ref: "./schemas/ingest/outputs.yaml#/Outputs"

    Rendition:
      $ref: "./schemas/ingest/rendition.yaml#/Rendition"

    Transcription:
      $ref: "./schemas/ingest/transcription.yaml#/Transcription"

    Speed:
      $ref: "./schemas/ingest/speed.yaml#/Speed"

    Enhancements:
      $ref: "./schemas/ingest/enhancements.yaml#/Enhancements"

    AudioEnhancement:
      $ref: "./schemas/ingest/enhancements/audioEnhancement.yaml#/AudioEnhancement"

    DolbyEnhancement:
      $ref: "./schemas/ingest/enhancements/audio/dolbyEnhancement.yaml#/DolbyEnhancement"

    DolbyEnhancementOptions:
      $ref: "./schemas/ingest/enhancements/audio/dolbyEnhancementOptions.yaml#/DolbyEnhancementOptions"

    # Serve schemas
    Transfer:
      $ref: "./schemas/serve/transfer.yaml#/Transfer"

    # Create schemas
    GeneratedAsset:
      $ref: "./schemas/create/generatedAsset.yaml#/GeneratedAsset"

    ShotstackGeneratedAsset:
      $ref: "./schemas/create/shotstackGeneratedAsset.yaml#/ShotstackGeneratedAsset"

    ShotstackGeneratedAssetOptions:
      $ref: "./schemas/create/shotstackGeneratedAssetOptions.yaml#/ShotstackGeneratedAssetOptions"

    ShotstackTextToSpeechOptions:
      $ref: "./schemas/create/shotstackTextToSpeechOptions.yaml#/ShotstackTextToSpeechOptions"

    ShotstackTextToImageOptions:
      $ref: "./schemas/create/shotstackTextToImageOptions.yaml#/ShotstackTextToImageOptions"

    ShotstackImageToVideoOptions:
      $ref: "./schemas/create/shotstackImageToVideoOptions.yaml#/ShotstackImageToVideoOptions"

    ShotstackTextGeneratorOptions:
      $ref: "./schemas/create/shotstackTextGeneratorOptions.yaml#/ShotstackTextGeneratorOptions"

    DIDGeneratedAsset:
      $ref: "./schemas/create/didGeneratedAsset.yaml#/DIDGeneratedAsset"

    DIDGeneratedAssetOptions:
      $ref: "./schemas/create/didGeneratedAssetOptions.yaml#/DIDGeneratedAssetOptions"

    DIDTextToAvatarOptions:
      $ref: "./schemas/create/didTextToAvatarOptions.yaml#/DIDTextToAvatarOptions"

    ElevenLabsGeneratedAsset:
      $ref: "./schemas/create/elevenlabsGeneratedAsset.yaml#/ElevenLabsGeneratedAsset"

    ElevenLabsGeneratedAssetOptions:
      $ref: "./schemas/create/elevenlabsGeneratedAssetOptions.yaml#/ElevenLabsGeneratedAssetOptions"

    ElevenLabsTextToSpeechOptions:
      $ref: "./schemas/create/elevenlabsTextToSpeechOptions.yaml#/ElevenLabsTextToSpeechOptions"

    HeyGenGeneratedAsset:
      $ref: "./schemas/create/heygenGeneratedAsset.yaml#/HeyGenGeneratedAsset"

    HeyGenGeneratedAssetOptions:
      $ref: "./schemas/create/heygenGeneratedAssetOptions.yaml#/HeyGenGeneratedAssetOptions"

    HeyGenTextToAvatarOptions:
      $ref: "./schemas/create/heygenTextToAvatarOptions.yaml#/HeyGenTextToAvatarOptions"

    OpenAiGeneratedAsset:
      $ref: "./schemas/create/openaiGeneratedAsset.yaml#/OpenAiGeneratedAsset"

    OpenAiGeneratedAssetOptions:
      $ref: "./schemas/create/openaiGeneratedAssetOptions.yaml#/OpenAiGeneratedAssetOptions"

    OpenAiTextGeneratorOptions:
      $ref: "./schemas/create/openaiTextGeneratorOptions.yaml#/OpenAiTextGeneratorOptions"

    StabilityAiGeneratedAsset:
      $ref: "./schemas/create/stabilityAiGeneratedAsset.yaml#/StabilityAiGeneratedAsset"

    StabilityAiGeneratedAssetOptions:
      $ref: "./schemas/create/stabilityAiGeneratedAssetOptions.yaml#/StabilityAiGeneratedAssetOptions"

    StabilityAiTextToImageOptions:
      $ref: "./schemas/create/stabilityAiTextToImageOptions.yaml#/StabilityAiTextToImageOptions"

    # Edit response schemas
    QueuedResponse:
      $ref: "./schemas/responses/queuedresponse.yaml#/QueuedResponse"

    QueuedResponseData:
      $ref: "./schemas/responses/queuedresponsedata.yaml#/QueuedResponseData"

    RenderResponse:
      $ref: "./schemas/responses/renderresponse.yaml#/RenderResponse"

    RenderResponseData:
      $ref: "./schemas/responses/renderresponsedata.yaml#/RenderResponseData"

    TemplateResponse:
      $ref: "./schemas/responses/templateresponse.yaml#/TemplateResponse"

    TemplateResponseData:
      $ref: "./schemas/responses/templateresponsedata.yaml#/TemplateResponseData"

    TemplateDataResponse:
      $ref: "./schemas/responses/templatedataresponse.yaml#/TemplateDataResponse"

    TemplateDataResponseData:
      $ref: "./schemas/responses/templatedataresponsedata.yaml#/TemplateDataResponseData"

    TemplateListResponse:
      $ref: "./schemas/responses/templatelistresponse.yaml#/TemplateListResponse"

    TemplateListResponseData:
      $ref: "./schemas/responses/templatelistresponsedata.yaml#/TemplateListResponseData"

    TemplateListResponseItem:
      $ref: "./schemas/responses/templatelistresponseitem.yaml#/TemplateListResponseItem"

    ProbeResponse:
      $ref: "./schemas/responses/proberesponse.yaml#/ProbeResponse"

    AssetResponse:
      $ref: "./schemas/responses/assetresponse.yaml#/AssetResponse"

    AssetRenderResponse:
      $ref: "./schemas/responses/assetrenderresponse.yaml#/AssetRenderResponse"

    AssetResponseData:
      $ref: "./schemas/responses/assetresponsedata.yaml#/AssetResponseData"

    AssetResponseAttributes:
      $ref: "./schemas/responses/assetresponseattributes.yaml#/AssetResponseAttributes"

    # Serve response schemas
    TransferResponse:
      $ref: "./schemas/serve/responses/transferresponse.yaml#/TransferResponse"

    TransferResponseData:
      $ref: "./schemas/serve/responses/transferresponsedata.yaml#/TransferResponseData"

    TransferResponseAttributes:
      $ref: "./schemas/serve/responses/transferresponseattributes.yaml#/TransferResponseAttributes"

    # Ingest response schemas
    QueuedSourceResponse:
      $ref: "./schemas/ingest/responses/queuedsourceresponse.yaml#/QueuedSourceResponse"

    QueuedSourceResponseData:
      $ref: "./schemas/ingest/responses/queuedsourceresponsedata.yaml#/QueuedSourceResponseData"

    SourceListResponse:
      $ref: "./schemas/ingest/responses/sourcelistresponse.yaml#/SourceListResponse"

    SourceResponse:
      $ref: "./schemas/ingest/responses/sourceresponse.yaml#/SourceResponse"

    SourceResponseData:
      $ref: "./schemas/ingest/responses/sourceresponsedata.yaml#/SourceResponseData"

    SourceResponseAttributes:
      $ref: "./schemas/ingest/responses/sourceresponseattributes.yaml#/SourceResponseAttributes"

    OutputsResponse:
      $ref: "./schemas/ingest/responses/outputsresponse.yaml#/OutputsResponse"

    RenditionResponseAttributes:
      $ref: "./schemas/ingest/responses/renditionresponseattributes.yaml#/RenditionResponseAttributes"

    UploadResponse:
      $ref: "./schemas/ingest/responses/uploadresponse.yaml#/UploadResponse"

    UploadResponseData:
      $ref: "./schemas/ingest/responses/uploadresponsedata.yaml#/UploadResponseData"

    UploadResponseAttributes:
      $ref: "./schemas/ingest/responses/uploadresponseattributes.yaml#/UploadResponseAttributes"

    IngestErrorResponse:
      $ref: "./schemas/ingest/responses/ingesterrorresponse.yaml#/IngestErrorResponse"

    IngestErrorResponseData:
      $ref: "./schemas/ingest/responses/ingesterrorresponsedata.yaml#/IngestErrorResponseData"

    # Create response schemas
    GeneratedAssetResponse:
      $ref: "./schemas/create/responses/generatedAssetResponse.yaml#/GeneratedAssetResponse"

    GeneratedAssetResponseData:
      $ref: "./schemas/create/responses/generatedAssetResponseData.yaml#/GeneratedAssetResponseData"

    GeneratedAssetResponseAttributes:
      $ref: "./schemas/create/responses/generatedAssetResponseAttributes.yaml#/GeneratedAssetResponseAttributes"

    GeneratedAssetErrorResponse:
      $ref: "./schemas/create/responses/generatedAssetErrorResponse.yaml#/GeneratedAssetErrorResponse"

    GeneratedAssetErrorResponseData:
      $ref: "./schemas/create/responses/generatedAssetErrorResponseData.yaml#/GeneratedAssetErrorResponseData"

  responses: {}
  parameters: {}
  examples: {}
  requestBodies: {}
  headers: {}
  securitySchemes:
    DeveloperKey:
      description: >-
        Set the **x-api-key** header with your provided key for the correct
        environment (v1 or stage). Include the header in all calls to the API
        that are secured with a key.
      type: apiKey
      in: header
      name: x-api-key
  links: {}
  callbacks: {}