openapi: 3.2.0
info:
  title: Gumlet Subtitle Upload API
  description: Gumlet helps developers deliver online video and images. This API encompasses Gumlet Video, Image and Video Analytics functionality to help you build your products better and faster than ever before.
  version: '1.4'
  contact:
    name: Gumlet Support Team
    url: https://www.gumlet.com/contact/
    email: support@gumlet.com
  termsOfService: https://www.gumlet.com/terms/
  license:
    name: Apache 2.0
    url: https://opensource.org/license/apache-2.0
  x-scalar-sdk-installation:
  - lang: TypeScript
    description: '```sh

      npm install @gumlet/nodejs-sdk

      ```'
  - lang: Python
    description: '```sh

      pip install gumlet

      ```'
servers:
- url: https://api.gumlet.com/v1
security:
- API_KEY: []
tags:
- name: Subtitle Upload
  description: Add subtitles to an existing asset.
paths:
  /video/assets/{asset_ID}/subtitle/upload:
    post:
      summary: Upload Subtitles
      description: Upload `.srt` or `.vtt` file to the video asset. The response of this API call gives `upload_url` for each language specified. You need to send a `PUT` request of the subtitle files to those URLs. Once that's done, you need to call the subtitle upload complete API. Only after that, Gumlet will add subtitles to asset.
      operationId: upload-subtitles
      parameters:
      - name: asset_ID
        in: path
        description: An asset id for the previously created asset.
        schema:
          type: string
        required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                language_codes:
                  type: array
                  description: List of language codes to upload subtitle file (use <a href='https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes'> ISO 639-1 </a> Language Codes)
                  items:
                    type: string
            examples:
              Example 1:
                value:
                  language_codes:
                  - en
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value:
                    signed_urls:
                    - language_code: en
                      upload_url: <UPLOAD_URL>
                    asset_id: 6a8491aaf180d34362c9587a
              schema:
                title: ''
                type: object
                properties:
                  asset_id:
                    type: string
                    description: Asset ID of Gumlet
                  signed_urls:
                    type: array
                    items:
                      type: object
                      properties:
                        language_code:
                          type: string
                        upload_url:
                          type: string
                      x-apidog-orders:
                      - language_code
                      - upload_url
                      required:
                      - language_code
                      - upload_url
                x-apidog-orders:
                - asset_id
                - signed_urls
                required:
                - asset_id
                - signed_urls
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Result:
                  value:
                    error:
                      code: invalid_language_code
                      message: Invalid language code. It must be one of the ISO 639-1 assigned codes.
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_language_code
                      message:
                        type: string
                        example: Invalid language code. It must be one of the ISO 639-1 assigned codes.
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      deprecated: false
      tags:
      - Subtitle Upload
      x-codeSamples:
      - label: TypeScript
        lang: TypeScript
        source: "import Gumlet from '@gumlet/nodejs-sdk';\n\nconst client = new Gumlet({\n  apiKey: process.env['API_KEY'], // defaults to the API_KEY env var\n});\n\nconst subtitleUpload = await client.subtitleUpload.upload('assetId');\n\nconsole.log(subtitleUpload);"
      - label: Python
        lang: Python
        source: "import os\n\nfrom gumlet import Gumlet\n\nclient = Gumlet(\n    api_key=os.environ.get(\"API_KEY\"),\n)\n\nsubtitle_upload = client.subtitle_upload.upload(\n    asset_id=\"assetId\",\n    language_codes=[\"en\"],\n)\n\nprint(subtitle_upload)"
  /video/assets/{asset_ID}/subtitle/upload/event:
    post:
      summary: Complete Subtitle Upload
      description: 'This API must be called after adding subtitles; the add subtitle call gives you URLs to upload, and you complete a `PUT` request to those URLs.

        Once that is done, calling this initiates the process to actually add the subtitle to the video.'
      operationId: complete-subtitle-upload
      parameters:
      - name: asset_ID
        in: path
        description: An asset id for the previously created asset.
        schema:
          type: string
        required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                upload_responses:
                  type: array
                  items:
                    properties:
                      language_code:
                        type: string
                        description: Language code for uploaded .srt or .vtt file.
                      uploaded:
                        type: boolean
                        description: Status of language uploaded .srt or .vtt file. (If status code was 200, You can mark true else false)
                    type: object
                    x-apidog-orders:
                    - language_code
                    - uploaded
              x-apidog-orders:
              - upload_responses
            examples:
              Example 1:
                value:
                  upload_responses:
                  - language_code: en
                    uploaded: true
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: {}
              schema:
                type: object
                properties: {}
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Result:
                  value:
                    error:
                      code: no_additional_track
                      message: No track request exists. Please upload a track first.
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: no_additional_track
                      message:
                        type: string
                        example: No track request exists. Please upload a track first.
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      deprecated: false
      tags:
      - Subtitle Upload
      x-codeSamples:
      - label: TypeScript
        lang: TypeScript
        source: "import Gumlet from '@gumlet/nodejs-sdk';\n\nconst client = new Gumlet({\n  apiKey: process.env['API_KEY'], // defaults to the API_KEY env var\n});\n\nconst subtitleUpload = await client.subtitleUpload.complete('assetId');\n\nconsole.log(subtitleUpload);"
      - label: Python
        lang: Python
        source: "import os\n\nfrom gumlet import Gumlet\n\nclient = Gumlet(\n    api_key=os.environ.get(\"API_KEY\"),\n)\n\nsubtitle_upload = client.subtitle_upload.complete(\n    asset_id=\"assetId\",\n    upload_responses=[{\"language_code\": \"en\", \"uploaded\": True}],\n)\n\nprint(subtitle_upload)"
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
            param:
              type: string
              description: Optional parameter name related to the error
  responses:
    Forbidden:
      description: Forbidden — unpaid account or insufficient role permissions
      content:
        application/json:
          examples:
            Result:
              value:
                error:
                  code: unauthorized
                  message: You don't have access to this feature. Please contact your organization owner.
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized — missing or invalid API key / bearer token
      content:
        application/json:
          examples:
            Result:
              value:
                error:
                  code: invalid_api_key
                  message: API key supplied with request is invalid
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          examples:
            Result:
              value:
                error:
                  code: internal_server_error
                  message: We have encountered some server error. We have been notified and will fix it soon.
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    API_KEY:
      type: http
      scheme: bearer
x-tagGroups:
- name: Video on Demand
  tags:
  - Video Assets
  - Global Search
  - Multipart Upload
  - Audio Upload
  - Subtitle Upload
  - Recycle Bin
  - Video Workspaces
  - Folders
  - Video Playlists
  - Channel Viewers
  - Video Usage Analytics
  - Video Profiles
  - Webhooks
- name: Live Streams
  tags:
  - Live Stream Workspaces
  - Live Stream Assets
  - Live Stream Analytics
- name: Image APIs
  tags:
  - Image Sources
  - Image Usage Analytics
- name: Video Analytics
  tags:
  - Video Analytics
- name: Webhooks
  tags:
  - Webhooks
- name: Account Endpoints
  tags:
  - User Data
  - Billing
  - Organization Data
  - Audit Logs
x-ext-urls: {}