Picsart Metadata API

openapi: 3.0.0
info:
  version: '1.0'
  title: Picsart GenAI Ads Metadata API
  description: '[Official technical documentation portal](https://docs.picsart.io/)

    [Developer Guidelines](https://picsart.io/terms)

    '
servers:
- url: https://genai-api.picsart.io/v1
  description: Production
security:
- apiKey: []
tags:
- name: Metadata
paths:
  /metadata:
    post:
      summary: Get Video Metadata
      operationId: video-metadata
      description: 'Analysis the Video and provides the Metadata.

        '
      tags:
      - Metadata
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/VideoParameters'
      responses:
        '200':
          $ref: '#/components/responses/200Metadata'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '413':
          $ref: '#/components/responses/413'
        '415':
          $ref: '#/components/responses/415'
        '429':
          $ref: '#/components/responses/429'
        '431':
          $ref: '#/components/responses/431'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /metadata/thumbnail/extract:
    post:
      summary: Get Video Thumbnail
      operationId: video-get-thumbnail
      description: 'Extracts (reads) Video Thumbnail.

        '
      tags:
      - Metadata
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/VideoParameters'
              - $ref: '#/components/schemas/VideoGetThumbnailParameters'
      responses:
        '200':
          $ref: '#/components/responses/200Thumbnails'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '413':
          $ref: '#/components/responses/413'
        '415':
          $ref: '#/components/responses/415'
        '429':
          $ref: '#/components/responses/429'
        '431':
          $ref: '#/components/responses/431'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /metadata/thumbnail:
    post:
      summary: Set Video Thumbnail
      operationId: video-set-thumbnail
      description: 'Update/Set the Video Thumbnail.

        '
      tags:
      - Metadata
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/VideoParameters'
              - $ref: '#/components/schemas/ImageParameters'
      responses:
        '202':
          $ref: '#/components/responses/202'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '413':
          $ref: '#/components/responses/413'
        '415':
          $ref: '#/components/responses/415'
        '429':
          $ref: '#/components/responses/429'
        '431':
          $ref: '#/components/responses/431'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /metadata/thumbnail/{transaction_id}:
    get:
      summary: Get the Video with updated Thumbnail
      operationId: video-set-thumbnail-getresult
      description: 'Use this method, along with transaction_id, to retrieve the updated video with the new thumbnail.

        '
      tags:
      - Metadata
      parameters:
      - in: path
        name: transaction_id
        schema:
          type: string
        required: true
        description: The ID returned from the POST method when it's done asynchronously.
      responses:
        '200':
          $ref: '#/components/responses/200'
        '202':
          $ref: '#/components/responses/202'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '413':
          $ref: '#/components/responses/413'
        '415':
          $ref: '#/components/responses/415'
        '429':
          $ref: '#/components/responses/429'
        '431':
          $ref: '#/components/responses/431'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
components:
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    '402':
      description: Payment Required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    200Thumbnails:
      description: Success.
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      nullable: true
                    url:
                      type: string
                      format: uri
                      nullable: false
                  minItems: 0
                  maxItems: 4
              status:
                type: string
                enum:
                - success
                - error
                - processing
                - queued
                nullable: false
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/401_Error'
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    '429':
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    '431':
      description: Request Header Fields Too Large
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    '413':
      description: Request Entity Too Large
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    200Metadata:
      description: Success.
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  video_streams:
                    type: integer
                    description: Number of video streams in the file (including thumbnails)
                    nullable: true
                  audio_streams:
                    type: integer
                    description: Number of audio streams in the file
                    nullable: true
                  bit_rate:
                    type: integer
                    description: Overall bit rate of the file in bits per second
                    nullable: true
                  size:
                    type: integer
                    description: File size in bytes
                    nullable: true
                  duration:
                    type: number
                    description: Total duration of the file in seconds
                    nullable: true
                  format_name:
                    type: string
                    description: Container format name
                    nullable: true
                  video_codec_name:
                    type: string
                    description: Video codec name
                    nullable: true
                  video_width:
                    type: integer
                    description: Video width in pixels
                    nullable: true
                  video_height:
                    type: integer
                    description: Video height in pixels
                    nullable: true
                  video_duration:
                    type: number
                    description: Video stream duration in seconds
                    nullable: true
                  video_bit_rate:
                    type: integer
                    description: Video stream bit rate in bits per second
                    nullable: true
                  video_pix_fmt:
                    type: string
                    description: Video pixel format
                    nullable: true
                  video_fps:
                    type: integer
                    description: Video frame rate (frames per second)
                    nullable: true
                  audio_codec_name:
                    type: string
                    description: Audio codec name
                    nullable: true
                  audio_sample_rate:
                    type: integer
                    description: Audio sample rate in Hz
                    nullable: true
                  audio_channels:
                    type: integer
                    description: Number of audio channels
                    nullable: true
                  audio_channel_layout:
                    type: string
                    description: Audio channel layout
                    nullable: true
                  audio_duration:
                    type: number
                    description: Audio stream duration in seconds
                    nullable: true
                  audio_bit_rate:
                    type: integer
                    description: Audio stream bit rate in bits per second
                    nullable: true
                  thumbnail_codec_name:
                    type: string
                    description: Thumbnail codec name
                    nullable: true
                  thumbnail_width:
                    type: integer
                    description: Thumbnail width in pixels
                    nullable: true
                  thumbnail_height:
                    type: integer
                    description: Thumbnail height in pixels
                    nullable: true
                  thumbnail_pix_fmt:
                    type: string
                    description: Thumbnail pixel format
                    nullable: true
              status:
                type: string
                enum:
                - success
                - error
                - processing
                - queued
                nullable: false
          example:
            status: success
            video:
              id: 75c68cf6-9881-46a5-a3e8-6907640901eb
              url: https://cdn.picsart.io/d04d0fd0-192f-4532-bd9a-aa63a728e39c.mp4
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    '200':
      description: Success.
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  id:
                    type: string
                    nullable: true
                  url:
                    type: string
                    format: uri
                    nullable: false
              status:
                type: string
                enum:
                - success
                - error
                - processing
                - queued
                nullable: false
          example:
            status: success
            data:
              id: 75c68cf6-9881-46a5-a3e8-6907640901eb
              url: https://cdn.picsart.io/d04d0fd0-192f-4532-bd9a-aa63a728e39c.mp4
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    '202':
      description: Request successfully accepted for an asynchronous transformation.
      content:
        application/json:
          schema:
            type: object
            properties:
              transaction_id:
                type: string
                nullable: true
              status:
                type: string
                enum:
                - success
                - error
                - processing
                - queued
                nullable: false
          example:
            value:
              transaction_id: 931aed0a-5efd-4b62-9712-069b7147eec5
              status: processing
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    '405':
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    '503':
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    '404':
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
    '415':
      description: Unsupported Media Type
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        X-Picsart-Correlation-Id:
          schema:
            type: string
          description: The id which will help for troubleshooting request chain in the system.
        X-Picsart-Ratelimit-Available:
          schema:
            type: integer
          description: The number of available calls within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Limit:
          schema:
            type: integer
          description: The total number of requests that can be done within the timeframe. See the X-Picsart-Ratelimit-Reset-Time.
        X-Picsart-Ratelimit-Reset-Time:
          schema:
            type: integer
          description: The time when the used request count resets and the number of available calls gets equal to the total number.
        X-Picsart-Credit-Available:
          schema:
            type: integer
          description: The remaining number of the credits on the balance.
  schemas:
    VideoGetThumbnailParameters:
      type: object
      properties:
        source:
          type: string
          default: auto
          enum:
          - auto
          - container
          - timestamp
        timestamps:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 4
          nullable: true
          description: 'List up to 4 timestamps to extract frames from.  <a href="https://docs.picsart.io/docs/video-timestamps/">Several timestamp formats</a> are supported.

            '
    Error:
      type: object
      properties:
        message:
          type: string
        detail:
          type: string
      required:
      - detail
    VideoParameters:
      type: object
      properties:
        video_url:
          type: string
          description: Source video URL.
          maxLength: 2083
          minLength: 1
          format: uri
    ImageParameters:
      type: object
      properties:
        image:
          description: Source image file (binary). (If this parameter is present, the other image source parameters must be empty.)
          type: string
          format: binary
        image_url:
          type: string
          description: Source image URL. (If this parameter is present, the other image source parameters must be empty.)
          maxLength: 2083
          minLength: 1
          format: uri
    401_Error:
      type: object
      properties:
        code:
          type: integer
          example: 401
        message:
          type: string
          example: Unauthorized
        detail:
          type: string
      required:
      - detail
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Picsart-API-Key