Freepik Audio Isolation API

openapi: 3.2.0
info:
  description: The Magnific API is your gateway to a vast collection of high-quality digital resources for your applications and projects. As a leading platform, it offers a wide range of graphics, including vectors, photos, illustrations, icons, PSD templates, and more, all curated by talented designers from around the world.
  title: Magnific Audio Isolation API
  version: 1.0.0
servers:
- description: B2B API Production V1
  url: https://api.magnific.com
security:
- magnificApiKey: []
tags:
- name: audio-isolation
paths:
  /v1/ai/audio-isolation:
    get:
      description: Get the status of all audio isolation tasks
      operationId: get_all_audio_isolation_tasks
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  $ref: '#/components/examples/200-tasks-list'
              schema:
                $ref: '#/components/schemas/get_all_sound_effects_tasks_200_response'
          description: OK - List of audio isolation tasks
        '400':
          $ref: '#/components/responses/400-bad-request'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '500':
          $ref: '#/components/responses/500-internal-server-error'
        '503':
          $ref: '#/components/responses/503-service-unavailable'
      summary: Audio Isolation - List tasks
      tags:
      - audio-isolation
    post:
      description: 'Isolate and extract specific sounds from audio or video files using SAM Audio AI technology.

        Describe the sound you want to isolate, and the API separates it from background noise.


        **Use cases:**

        - Extract speech from noisy recordings

        - Isolate musical instruments from a mix

        - Separate specific sound effects from video audio

        - Remove background noise while preserving target sounds


        **Input options:**

        - Provide either an `audio` URL/base64 or a `video` URL/base64 (mutually exclusive)

        - Supported audio formats: WAV, MP3, FLAC, OGG, M4A

        - Supported video formats: MP4, MOV, WEBM, AVI

        - For video input, use bounding box coordinates (x1, y1, x2, y2) to focus on a specific region


        **Output:** WAV audio file containing the isolated sound'
      operationId: create_audio_isolation_task
      requestBody:
        content:
          application/json:
            examples:
              audio-input:
                summary: Isolate speech from audio
                value:
                  description: A person speaking
                  audio: https://example.com/noisy-recording.wav
              video-input:
                summary: Isolate sound from video region
                value:
                  description: Piano playing
                  video: https://example.com/concert.mp4
                  x1: 100
                  y1: 50
                  x2: 400
                  y2: 300
                  sample_fps: 2
            schema:
              $ref: '#/components/schemas/request_14'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/task-detail-200-default-response'
        '400':
          $ref: '#/components/responses/400-bad-request'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '500':
          $ref: '#/components/responses/500-internal-server-error'
        '503':
          $ref: '#/components/responses/503-service-unavailable'
      summary: Audio Isolation - Extract sounds from audio/video
      tags:
      - audio-isolation
  /v1/ai/audio-isolation/{task-id}:
    get:
      description: Get the status of one audio isolation task
      operationId: get_audio_isolation_task_status
      parameters:
      - description: ID of the task
        in: path
        name: task-id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                success - completed task:
                  $ref: '#/components/examples/200-task-completed'
                success - in progress task:
                  $ref: '#/components/examples/200-task-in-progress'
              schema:
                $ref: '#/components/schemas/get_style_transfer_task_status_200_response'
          description: OK - The task exists and the status is returned
        '400':
          $ref: '#/components/responses/400-bad-request'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '500':
          $ref: '#/components/responses/500-internal-server-error'
        '503':
          $ref: '#/components/responses/503-service-unavailable'
      summary: Audio Isolation - Get task status
      tags:
      - audio-isolation
components:
  schemas:
    inline_object_4:
      example:
        data:
          generated:
          - https://openapi-generator.tech
          - https://openapi-generator.tech
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: CREATED
      properties:
        data:
          $ref: '#/components/schemas/task-detail_1'
      required:
      - data
      type: object
    inline_object_1_problem_invalid_params_inner:
      properties:
        name:
          description: Name of the invalid parameter.
          example: page
          type: string
        field:
          description: Field of the invalid parameter. Mirrors `name`.
          example: page
          type: string
        reason:
          example: Parameter 'page' must be greater than 0
          type: string
      required:
      - field
      - name
      - reason
      type: object
    task:
      example:
        task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        status: CREATED
      properties:
        task_id:
          description: Task identifier
          format: uuid
          type: string
        status:
          description: Task status
          enum:
          - CREATED
          - IN_PROGRESS
          - COMPLETED
          - FAILED
          type: string
      required:
      - status
      - task_id
      type: object
    inline_object_1:
      properties:
        problem:
          $ref: '#/components/schemas/inline_object_1_problem'
      type: object
    inline_object_1_problem:
      properties:
        message:
          example: Validation error
          type: string
        invalid_params:
          items:
            $ref: '#/components/schemas/inline_object_1_problem_invalid_params_inner'
          type: array
      required:
      - invalid_params
      - message
      type: object
    inline_object_2:
      example:
        message: Internal Server Error
      properties:
        message:
          example: Internal Server Error
          type: string
      type: object
    request_14:
      properties:
        description:
          description: Text description of the sound to isolate from the input audio or video. Be specific about the type of sound you want to extract.
          example: A person speaking
          maxLength: 2500
          type: string
        audio:
          description: 'Audio input - either a publicly accessible HTTPS URL or base64 encoded audio. Supported formats: WAV, MP3, FLAC, OGG, M4A. Mutually exclusive with `video`.'
          example: https://example.com/input-audio.wav
          type: string
        video:
          description: 'Video input - either a publicly accessible HTTPS URL or base64 encoded video. Supported formats: MP4, MOV, WEBM, AVI. Mutually exclusive with `audio`.'
          example: https://example.com/input-video.mp4
          type: string
        x1:
          default: 0
          description: Bounding box x1 coordinate (left edge) in pixels for sound source localization. Only applicable for video input.
          example: 100
          minimum: 0
          type: integer
        y1:
          default: 0
          description: Bounding box y1 coordinate (top edge) in pixels for sound source localization. Only applicable for video input.
          example: 50
          minimum: 0
          type: integer
        x2:
          default: 0
          description: Bounding box x2 coordinate (right edge) in pixels for sound source localization. Only applicable for video input.
          example: 400
          minimum: 0
          type: integer
        y2:
          default: 0
          description: Bounding box y2 coordinate (bottom edge) in pixels for sound source localization. Only applicable for video input.
          example: 300
          minimum: 0
          type: integer
        sample_fps:
          default: 2
          description: Frame sampling rate in FPS for video processing. Higher values provide more temporal precision but increase processing time.
          example: 2
          maximum: 5
          minimum: 1
          type: number
        reranking_candidates:
          default: 1
          description: Number of reranking candidates for quality vs latency trade-off. Higher values produce better quality but slower processing.
          example: 1
          maximum: 8
          minimum: 1
          type: integer
        predict_spans:
          default: false
          description: Enable span prediction for better isolation of non-ambient sounds like speech or musical notes.
          example: false
          type: boolean
        webhook_url:
          description: 'Optional callback URL that will receive asynchronous notifications whenever the task changes status. The payload sent to this URL is the same as the corresponding GET endpoint response, but without the data field.

            '
          example: https://www.example.com/webhook
          format: uri
          type: string
      required:
      - description
      type: object
    inline_object:
      example:
        message: message
      properties:
        message:
          type: string
      type: object
    get_style_transfer_task_status_200_response:
      example:
        data:
          generated:
          - https://openapi-generator.tech
          - https://openapi-generator.tech
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: CREATED
      properties:
        data:
          $ref: '#/components/schemas/task-detail'
      required:
      - data
      type: object
    inline_object_3:
      example:
        message: Service Unavailable. Please try again later.
      properties:
        message:
          example: Service Unavailable. Please try again later.
          type: string
      type: object
    get_all_sound_effects_tasks_200_response:
      example:
        data:
        - generated:
          - https://openapi-generator.tech
          - https://openapi-generator.tech
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: CREATED
        - generated:
          - https://openapi-generator.tech
          - https://openapi-generator.tech
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: CREATED
      properties:
        data:
          items:
            $ref: '#/components/schemas/task-detail'
          type: array
      type: object
    task-detail:
      allOf:
      - $ref: '#/components/schemas/task'
      - properties:
          generated:
            items:
              description: URL of the generated image
              format: uri
              type: string
            type: array
        required:
        - generated
        type: object
      example:
        generated:
        - https://openapi-generator.tech
        - https://openapi-generator.tech
        task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        status: CREATED
    task-detail_1:
      allOf:
      - $ref: '#/components/schemas/task'
      - properties:
          generated:
            items:
              description: URL of the generated image
              format: uri
              type: string
            type: array
        required:
        - generated
        type: object
      example:
        generated:
        - https://openapi-generator.tech
        - https://openapi-generator.tech
        task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        status: CREATED
  responses:
    401-unauthorized:
      content:
        application/json:
          examples:
            invalid_api_key:
              summary: API key is not valid
              value:
                message: Invalid API key
            missing_api_key:
              summary: API key is not provided
              value:
                message: Missing API key
          schema:
            $ref: '#/components/schemas/inline_object'
      description: Unauthorized - The client must authenticate itself to get the requested response.
    503-service-unavailable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/inline_object_3'
      description: Service Unavailable
    task-detail-200-default-response:
      content:
        application/json:
          examples:
            success - created task:
              $ref: '#/components/examples/200-task-created'
            success - in progress task:
              $ref: '#/components/examples/200-task-in-progress'
            success - completed task:
              $ref: '#/components/examples/200-task-completed'
            success - failed task:
              $ref: '#/components/examples/200-task-failed'
          schema:
            $ref: '#/components/schemas/inline_object_4'
      description: OK - The task exists and the status is returned
    400-bad-request:
      content:
        application/json:
          examples:
            invalid_page:
              summary: Parameter 'page' is not valid
              value:
                message: Parameter 'page' must be greater than 0
            invalid_query:
              summary: Parameter 'query' is not valid
              value:
                message: Parameter 'query' must not be empty
            invalid_filter:
              summary: Parameter 'filter' is not valid
              value:
                message: Parameter 'filter' is not valid
            generic_bad_request:
              summary: Bad Request
              value:
                message: Parameter ':attribute' is not valid
          schema:
            $ref: '#/components/schemas/inline_object'
        application/problem+json:
          examples:
            invalid_page:
              summary: Parameter 'page' is not valid
              value:
                message: Validation error
                invalid_params:
                - field: page
                  reason: Parameter 'page' must be greater than 0
                - field: per_page
                  reason: Parameter 'per_page' must be greater than 0
          schema:
            $ref: '#/components/schemas/inline_object_1'
      description: Bad Request - The server could not understand the request due to invalid syntax.
    500-internal-server-error:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/inline_object_2'
      description: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
  examples:
    200-task-failed:
      summary: Success - Task failed
      value:
        data:
          generated: []
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: FAILED
    200-tasks-list:
      summary: Success - Return all tasks
      value:
        data:
        - task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: IN_PROGRESS
        - task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee92
          status: COMPLETED
        - task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee93
          status: COMPLETED
        - task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee93
          status: CREATED
    200-task-in-progress:
      summary: Success - Task in progress
      value:
        data:
          generated: []
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: IN_PROGRESS
    200-task-created:
      summary: Success - Task created
      value:
        data:
          generated: []
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: CREATED
    200-task-completed:
      summary: Success - Task completed
      value:
        data:
          generated:
          - https://ai-statics.freepik.com/completed_task_image.jpg
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: COMPLETED
  securitySchemes:
    magnificApiKey:
      description: 'Your Magnific API key. Required for authentication. [Learn how to obtain an API key](https://docs.magnific.com/quickstart)

        '
      in: header
      name: x-magnific-api-key
      type: apiKey
x-provenance:
  method: harvested
  publisher: Freepik
  source: https://storage.googleapis.com/fc-freepik-pro-rev1-eu-api-specs/magnific-api-v1-openapi.yaml?v=46\
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)