Freepik Video Edit 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 Video Edit API
  version: 1.0.0
servers:
- description: B2B API Production V1
  url: https://api.magnific.com
security:
- magnificApiKey: []
tags:
- name: video-edit
paths:
  /v1/ai/video-edit/wan-2-7:
    get:
      description: Retrieve the list of all WAN 2.7 video edit tasks for the authenticated user.
      operationId: get_all_wan_27_video_edit_tasks
      responses:
        '200':
          $ref: '#/components/responses/task-list-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: WAN 2.7 Video Edit - List tasks
      tags:
      - video-edit
    post:
      description: 'Edit an existing video using WAN 2.7. Transform video content with text instructions, apply visual references, or transfer artistic styles.


        **Three editing modes:**

        - **Instruction-based editing**: Provide `prompt` with editing instructions (e.g., "change the sky to sunset")

        - **Reference-image editing**: Provide `prompt` and `image_urls` to apply visual references to the video

        - **Style transfer**: Provide `prompt` and `image_urls` with style reference images to transfer artistic styles


        **Key features:**

        - 720P and 1080P resolution support

        - Up to 3 reference images for editing or style transfer

        - Set `duration` to `0` to preserve the full input video duration

        - Configurable audio handling: auto-generate or preserve original'
      operationId: create_video_wan_27_edit
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/video-edit-request'
        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: WAN 2.7 - Edit video
      tags:
      - video-edit
  /v1/ai/video-edit/wan-2-7/{task-id}:
    get:
      description: Retrieve the status and result of a specific WAN 2.7 video edit task by its ID.
      operationId: get_wan_27_video_edit_task
      parameters:
      - description: ID of the task
        in: path
        name: task-id
        required: true
        schema:
          type: string
      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: WAN 2.7 Video Edit - Get task status
      tags:
      - video-edit
  /v1/ai/video-edit/happy-horse-1:
    get:
      description: Retrieve the list of all Happy Horse 1.0 video edit tasks for the authenticated user.
      operationId: get_all_happy_horse_1_video_edit_tasks
      responses:
        '200':
          $ref: '#/components/responses/task-list-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: Happy Horse 1.0 Video Edit - List tasks
      tags:
      - video-edit
    post:
      description: 'Edit an existing video with natural-language instructions using Happy Horse 1.0, Alibaba''s AI video editing model, optionally guided by up to 5 reference images.


        **Editing modes:**

        - **Instruction-based editing**: Provide `prompt` with editing instructions (e.g., "change the sky to sunset")

        - **Reference-image editing**: Provide `prompt` and `image_urls`, then reference images from the prompt using `@Image1`..`@Image5` (1-based, in array order)


        **Key features:**

        - 720P and 1080P resolution support

        - Up to 5 reference images

        - Output is capped at 15 seconds

        - Configurable audio handling: `auto` (regenerate when relevant) or `origin` (preserve input audio)'
      operationId: create_video_happy_horse_1_edit
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/video-edit-request_1'
        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: Happy Horse 1.0 - Edit video
      tags:
      - video-edit
  /v1/ai/video-edit/happy-horse-1/{task-id}:
    get:
      description: Retrieve the status and result of a specific Happy Horse 1.0 video edit task by its ID.
      operationId: get_happy_horse_1_video_edit_task
      parameters:
      - description: ID of the task
        in: path
        name: task-id
        required: true
        schema:
          type: string
      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: Happy Horse 1.0 Video Edit - Get task status
      tags:
      - video-edit
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
    resolution:
      default: 1080P
      description: 'Output video resolution:

        - `720P`: 720p HD (1280x720)

        - `1080P`: 1080p Full HD (1920x1080)

        '
      enum:
      - 720P
      - 1080P
      type: string
    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
    video-edit-request:
      description: 'Edit an existing video using WAN 2.7. Supports three modes:

        - Instruction-based editing: provide `prompt` with editing instructions (e.g., "change the sky to sunset")

        - Reference-image editing: provide `prompt` and `image_urls` to apply visual references to the video

        - Style transfer: provide `prompt` and `image_urls` with style reference images to transfer artistic styles

        '
      properties:
        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
        prompt:
          description: Editing instructions describing the desired changes. For reference-image or style-transfer modes, describe how the reference images should be applied.
          example: Change the background to a futuristic cityscape with neon lights
          maxLength: 5000
          type: string
        negative_prompt:
          description: Elements to avoid in the edited video.
          example: watermark, text, distortion, blurry
          maxLength: 500
          type: string
        video_url:
          description: 'URL of the input video to edit. Must be publicly accessible.


            **Supported formats:** MP4, MOV

            **Duration:** 2-10 seconds

            **Dimensions:** 240-4096px per side, aspect ratio between 1:8 and 8:1

            **Maximum file size:** 100MB

            '
          example: https://example.com/input-video.mp4
          format: uri
          type: string
        image_urls:
          description: 'Reference images for editing or style transfer. Up to 3 images.


            **Supported formats:** JPEG, PNG, BMP, WEBP

            **Dimensions:** 240-8000px per side

            **Maximum file size:** 20MB each

            '
          example:
          - https://example.com/reference1.jpg
          items:
            format: uri
            type: string
          maxItems: 3
          type: array
        aspect_ratio:
          $ref: '#/components/schemas/video-edit-aspect-ratio'
        resolution:
          $ref: '#/components/schemas/resolution'
        duration:
          default: 0
          description: Duration of the output video in seconds. Set to `0` to preserve the full duration of the input video.
          example: 0
          maximum: 10
          minimum: 0
          type: integer
        seed:
          description: Random seed for reproducible generation. Use the same seed with identical parameters to reproduce results. Leave unset for random seed.
          example: 12345
          maximum: 2147483647
          minimum: 0
          type: integer
        additional_settings:
          $ref: '#/components/schemas/video-edit-additional-settings'
      required:
      - video_url
      title: Video Edit - WAN 2.7
      type: object
    inline_object_1:
      properties:
        problem:
          $ref: '#/components/schemas/inline_object_1_problem'
      type: object
    video-edit-additional-settings:
      description: Additional settings for video editing.
      properties:
        audio_setting:
          $ref: '#/components/schemas/audio-setting'
        prompt_extend:
          default: true
          description: Enable automatic prompt expansion to enrich shorter prompts with additional detail for better editing results.
          example: true
          type: boolean
      type: object
    video-edit-request_1:
      description: 'Edit an existing video using natural-language instructions with Happy Horse 1.0, optionally guided by up to 5 reference images. Reference images from the prompt using `@Image1`..`@Image5` tokens (1-based, in array order). Output is capped at 15 seconds.

        '
      properties:
        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
        video_url:
          description: 'URL of the source video to be edited.


            **Supported formats:** MP4, MOV with H.264 codec

            **Duration:** between 3 and 60 seconds (the output is capped at 15 seconds)

            **Frame rate:** greater than 8 fps

            **Dimensions:** longer side at most 2160 px and shorter side at least 320 px

            **Aspect ratio:** between 1:2.5 and 2.5:1

            **Maximum file size:** 100 MB

            '
          example: https://example.com/input-video.mp4
          format: uri
          type: string
        prompt:
          description: 'Text prompt describing the desired editing instructions. To reference an image from `image_urls` inside the prompt, use the tokens `@Image1`..`@Image5` (1-based, matching the array order).


            **Example:** "Replace the background with a futuristic cityscape at night"

            '
          example: Replace the background with a futuristic cityscape at night
          maxLength: 2500
          minLength: 1
          type: string
        image_urls:
          description: 'Up to 5 reference images that guide the edit. Reference them from the prompt using `@Image1`..`@Image5` (1-based, in array order).


            **Supported formats:** JPEG, JPG, PNG, WEBP

            **Minimum dimension:** 300 px

            **Aspect ratio:** between 1:2.5 and 2.5:1

            **Maximum file size:** 10 MB per image

            '
          example:
          - https://example.com/reference1.jpg
          items:
            format: uri
            type: string
          maxItems: 5
          type: array
        resolution:
          $ref: '#/components/schemas/resolution'
        audio_setting:
          $ref: '#/components/schemas/audio-setting_1'
        seed:
          description: Random seed for reproducibility. Use the same seed with identical parameters to improve reproducibility (does not guarantee identical results). Leave unset for a random seed.
          example: 12345
          maximum: 2147483647
          minimum: 0
          type: integer
      required:
      - prompt
      - video_url
      title: Video Edit - Happy Horse 1.0
      type: object
    video-edit-aspect-ratio:
      description: 'Output video aspect ratio for editing. If not specified, the aspect ratio of the input video is preserved.

        - `16:9`: Landscape (widescreen)

        - `9:16`: Portrait (vertical, mobile-optimized)

        - `1:1`: Square

        - `4:3`: Standard landscape

        - `3:4`: Standard portrait

        '
      enum:
      - 969
      - 556
      - 61
      - 243
      - 184
      type: string
    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
    inline_object:
      example:
        message: message
      properties:
        message:
          type: string
      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
    audio-setting:
      default: auto
      description: 'Audio handling mode for the edited video:

        - `auto`: Automatically generate or adapt audio for the edited video

        - `origin`: Preserve the original audio from the input video

        '
      enum:
      - auto
      - origin
      type: string
    audio-setting_1:
      default: auto
      description: 'Audio handling mode for the edited video:

        - `auto`: The model decides whether to regenerate audio based on the prompt — if the prompt involves audio descriptions, audio may be regenerated; otherwise the original audio is preserved

        - `origin`: Force-preserve the input video''s original audio without regeneration

        '
      enum:
      - auto
      - origin
      type: string
    get_all_style_transfer_tasks_200_response:
      example:
        data:
        - task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: CREATED
        - task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: CREATED
      properties:
        data:
          items:
            $ref: '#/components/schemas/task'
          type: array
      required:
      - data
      type: object
    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.
    task-list-200-default-response:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/get_all_style_transfer_tasks_200_response'
      description: OK - Returns a list of tasks for the current type of Task
  examples:
    200-task-failed:
      summary: Success - Task failed
      value:
        data:
          generated: []
          task_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: FAILED
    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)