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

# Get video download URLs

> Returns every rendition YouTube serves for this video, each with a direct file URL you can download with a plain GET request — no cookies, auth headers, or special HTTP client needed. Renditions with `audioChannels` set are complete files; YouTube only serves those up to 360p. Above that, video and audio come separately, so combine a `video/*` and an `audio/*` rendition to get a playable file. URLs expire after a few hours — see `expiresAt`.



## OpenAPI

````yaml /openapi.json get /v1/youtube/videos/{videoId}/download
openapi: 3.1.0
info:
  title: KonbiniAPI
  version: 1.0.0
  description: >-
    Social media API that normalizes TikTok, Instagram, YouTube, Reddit, X, and
    LinkedIn data into a consistent ActivityStreams 2.0 format.


    Every authenticated response includes `X-Credits-Remaining` and
    `X-Credits-Used` headers. Each successful request costs 1 credit. Requests
    that fail with 400, 5xx, or upstream errors are refunded (X-Credits-Used:
    0).
  contact:
    name: KonbiniAPI
    email: hello@konbiniapi.com
    url: https://konbiniapi.com
servers:
  - url: https://api.konbiniapi.com
    description: Production
security:
  - apiKey: []
tags:
  - name: TikTok
    description: TikTok data endpoints
  - name: Instagram
    description: Instagram data endpoints
  - name: YouTube
    description: YouTube data endpoints
  - name: Reddit
    description: Reddit data endpoints
  - name: X
    description: X data endpoints
  - name: LinkedIn
    description: LinkedIn data endpoints
paths:
  /v1/youtube/videos/{videoId}/download:
    get:
      tags:
        - YouTube
      summary: Get video download URLs
      description: >-
        Returns every rendition YouTube serves for this video, each with a
        direct file URL you can download with a plain GET request — no cookies,
        auth headers, or special HTTP client needed. Renditions with
        `audioChannels` set are complete files; YouTube only serves those up to
        360p. Above that, video and audio come separately, so combine a
        `video/*` and an `audio/*` rendition to get a playable file. URLs expire
        after a few hours — see `expiresAt`.
      operationId: youtubeGetVideoDownloadUrl
      parameters:
        - schema:
            type: string
            description: YouTube video ID (the `v=` value from a watch URL)
            example: plN7JMbadRg
          required: true
          description: YouTube video ID (the `v=` value from a watch URL)
          name: videoId
          in: path
      responses:
        '200':
          description: Returns the download URL
          headers:
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credits remaining after this request
            X-Credits-Used:
              schema:
                type: integer
              description: Credits consumed (1 if charged, 0 if refunded on error)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      '@context':
                        type: array
                        prefixItems:
                          - type: string
                            enum:
                              - https://www.w3.org/ns/activitystreams#
                          - type: string
                            enum:
                              - https://konbiniapi.com/ns/social#
                        description: ActivityStreams JSON-LD context
                        example:
                          - https://www.w3.org/ns/activitystreams#
                          - https://konbiniapi.com/ns/social#
                      type:
                        type: string
                        enum:
                          - Collection
                        example: Collection
                      totalItems:
                        type: integer
                        description: Number of renditions returned
                        example: 115
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/YoutubeDownloadRendition'
                        description: >-
                          Every rendition YouTube serves for this video. Only
                          the 360p rendition (mediaType video/mp4 with
                          audioChannels set) is a complete, playable file on its
                          own — every other video/* rendition is silent, and
                          every audio/* rendition has no picture. Pick a video/*
                          and an audio/* rendition and mux them together to get
                          anything above 360p.
                      expiresAt:
                        type: string
                        format: date-time
                        example: '2026-10-18T16:58:23.801Z'
                        description: >-
                          When every URL in this response stops working
                          (absolute time, not a duration — still accurate no
                          matter how long you hold onto this response). Request
                          a fresh response rather than storing these URLs for
                          later.
                    required:
                      - '@context'
                      - type
                      - totalItems
                      - items
                required:
                  - data
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/CreditsExhaustedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '413':
          $ref: '#/components/responses/PayloadTooLargeError'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/PlatformError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
        '504':
          $ref: '#/components/responses/PlatformTimeoutError'
components:
  schemas:
    YoutubeDownloadRendition:
      type: object
      properties:
        type:
          type: string
          enum:
            - Video
            - Audio
          description: '"Audio" for an audio-only rendition, "Video" for anything else'
          example: Video
        entityId:
          type: string
          description: YouTube itag — the rendition ID
          example: '18'
        url:
          type: string
          format: uri
          description: >-
            Downloadable file URL for this rendition. Works with a plain GET
            request — no cookies, auth headers, or special HTTP client required.
          example: https://rr2---sn-uxax4vopj5xn-h5ql.googlevideo.com/videoplayback
        mediaType:
          type: string
          description: MIME type, including codecs
          example: video/mp4; codecs="avc1.42001E, mp4a.40.2"
        name:
          type: string
          example: 360p
          description: Resolution label
        width:
          type: integer
          example: 640
        height:
          type: integer
          example: 360
        fps:
          type: integer
          example: 30
        bitrate:
          type: integer
          example: 586287
          description: Bits per second
        size:
          type: integer
          example: 254935281
          description: File size in bytes
        duration:
          type: number
          example: 3479
          description: Duration in seconds
        audioChannels:
          type: integer
          example: 2
          description: Present only on a rendition that carries audio
        audioSampleRate:
          type: integer
          example: 44100
          description: Hz. Present only on a rendition that carries audio
      required:
        - type
        - entityId
        - url
        - mediaType
    ValidationError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - validation_error
                description: Machine-readable error code
              message:
                type: string
                example: Validation error
                description: Human-readable error message
            required:
              - code
              - message
          description: List of errors
        data:
          type: 'null'
          description: Always null for error responses
      required:
        - errors
        - data
    UnauthorizedError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - missing_api_key
                  - invalid_api_key
                description: Machine-readable error code
              message:
                type: string
                example: Invalid API key
                description: Human-readable error message
            required:
              - code
              - message
          description: List of errors
        data:
          type: 'null'
          description: Always null for error responses
      required:
        - errors
        - data
    CreditsExhaustedError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - credits_exhausted
                description: Machine-readable error code
              message:
                type: string
                example: Credits exhausted. Upgrade your plan at konbiniapi.com
                description: Human-readable error message
            required:
              - code
              - message
          description: List of errors
        data:
          type: 'null'
          description: Always null for error responses
      required:
        - errors
        - data
    ForbiddenError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - api_key_disabled
                  - api_key_expired
                description: Machine-readable error code
              message:
                type: string
                example: API key is disabled
                description: Human-readable error message
            required:
              - code
              - message
          description: List of errors
        data:
          type: 'null'
          description: Always null for error responses
      required:
        - errors
        - data
    NotFoundError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - not_found
                  - route_not_found
                description: Machine-readable error code
              message:
                type: string
                example: Not found
                description: Human-readable error message
            required:
              - code
              - message
          description: List of errors
        data:
          type: 'null'
          description: Always null for error responses
      required:
        - errors
        - data
    PayloadTooLargeError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - validation_error
                description: Machine-readable error code
              message:
                type: string
                example: Request body too large
                description: Human-readable error message
            required:
              - code
              - message
          description: List of errors
        data:
          type: 'null'
          description: Always null for error responses
      required:
        - errors
        - data
    InternalError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - internal_error
                description: Machine-readable error code
              message:
                type: string
                example: Internal error
                description: Human-readable error message
            required:
              - code
              - message
          description: List of errors
        data:
          type: 'null'
          description: Always null for error responses
      required:
        - errors
        - data
    PlatformError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - platform_error
                description: Machine-readable error code
              message:
                type: string
                example: Platform error
                description: Human-readable error message
            required:
              - code
              - message
          description: List of errors
        data:
          type: 'null'
          description: Always null for error responses
      required:
        - errors
        - data
    ServiceUnavailableError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - service_unavailable
                description: Machine-readable error code
              message:
                type: string
                example: Service unavailable
                description: Human-readable error message
            required:
              - code
              - message
          description: List of errors
        data:
          type: 'null'
          description: Always null for error responses
      required:
        - errors
        - data
    PlatformTimeoutError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - platform_error
                description: Machine-readable error code
              message:
                type: string
                example: Platform error
                description: Human-readable error message
            required:
              - code
              - message
          description: List of errors
        data:
          type: 'null'
          description: Always null for error responses
      required:
        - errors
        - data
  responses:
    ValidationError:
      description: Bad Request — Invalid parameters
      headers:
        X-Credits-Remaining:
          schema:
            type: integer
          description: Credits remaining after this request
        X-Credits-Used:
          schema:
            type: integer
          description: Credits consumed (1 if charged, 0 if refunded on error)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    UnauthorizedError:
      description: Unauthorized — Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
    CreditsExhaustedError:
      description: Payment Required — Credits exhausted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreditsExhaustedError'
    ForbiddenError:
      description: Forbidden — API key disabled or expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
    NotFoundError:
      description: Not Found
      headers:
        X-Credits-Remaining:
          schema:
            type: integer
          description: Credits remaining after this request
        X-Credits-Used:
          schema:
            type: integer
          description: Credits consumed (1 if charged, 0 if refunded on error)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    PayloadTooLargeError:
      description: Content Too Large — Request body exceeds 1 MB
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PayloadTooLargeError'
    InternalError:
      description: Internal Server Error
      headers:
        X-Credits-Remaining:
          schema:
            type: integer
          description: Credits remaining after this request
        X-Credits-Used:
          schema:
            type: integer
          description: Credits consumed (1 if charged, 0 if refunded on error)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalError'
    PlatformError:
      description: Bad Gateway — Upstream platform error
      headers:
        X-Credits-Remaining:
          schema:
            type: integer
          description: Credits remaining after this request
        X-Credits-Used:
          schema:
            type: integer
          description: Credits consumed (1 if charged, 0 if refunded on error)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformError'
    ServiceUnavailableError:
      description: Service Unavailable
      headers:
        X-Credits-Remaining:
          schema:
            type: integer
          description: Credits remaining after this request
        X-Credits-Used:
          schema:
            type: integer
          description: Credits consumed (1 if charged, 0 if refunded on error)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceUnavailableError'
    PlatformTimeoutError:
      description: Gateway Timeout — Upstream platform timed out
      headers:
        X-Credits-Remaining:
          schema:
            type: integer
          description: Credits remaining after this request
        X-Credits-Used:
          schema:
            type: integer
          description: Credits consumed (1 if charged, 0 if refunded on error)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformTimeoutError'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: |-
        Send your API key in the Authorization header as a Bearer token.
        Example: `Authorization: Bearer <your-api-key>`

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.