# Volcengine MediaKit video enhancement

> Video Generation

Submits an asynchronous video enhancement task. You must provide the source video via `input.video_url`.

`parameters` are optional. When omitted, the upstream service uses its own defaults. If you set `tool_version`, only `standard` is supported.

## Endpoint

`POST https://api.modelverse.cn/v1/tasks/submit`

## Request Body

## Responses

- **200** — Task submitted successfully.
- **400** — Invalid request parameters or input combination.
- **default** — Error response.

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "Volcengine MediaKit Video Enhancement API",
    "version": "1.0.0",
    "description": "This document describes the ModelVerse API for `ai-mediakit-video-enhancement-std`, an asynchronous video enhancement service powered by Volcengine MediaKit.\nThe endpoints are `POST /v1/tasks/submit` and `GET /v1/tasks/status`.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint used by this model document."
    }
  ],
  "tags": [
    {
      "name": "Volcengine MediaKit Video Enhancement",
      "description": "Asynchronous video enhancement with Volcengine MediaKit."
    }
  ],
  "paths": {
    "/v1/tasks/submit": {
      "post": {
        "tags": [
          "Volcengine MediaKit Video Enhancement"
        ],
        "operationId": "submitVolcengineMediakitVideoEnhancementTask",
        "summary": "Volcengine MediaKit video enhancement",
        "description": "Submits an asynchronous video enhancement task. You must provide the source video via `input.video_url`.\n\n`parameters` are optional. When omitted, the upstream service uses its own defaults. If you set `tool_version`, only `standard` is supported.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MediakitVideoEnhancementSubmitRequest"
              },
              "examples": {
                "simple": {
                  "summary": "Enhance by direct video URL",
                  "value": {
                    "model": "ai-mediakit-video-enhancement-std",
                    "input": {
                      "video_url": "https://vod-ai-test.tos-cn-beijing.volces.com/demo/demo_video_scenery_720p.mp4"
                    },
                    "parameters": {
                      "tool_version": "standard",
                      "enhance_style": "natural",
                      "bitrate": 8000,
                      "fps": 21
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task submitted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediakitVideoEnhancementSubmitResponse"
                },
                "examples": {
                  "submitted": {
                    "summary": "Submitted task",
                    "value": {
                      "output": {
                        "task_id": "mk-xxxxxxxxxxxx"
                      },
                      "request_id": "req_xxxxxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters or input combination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediakitVideoEnhancementErrorResponse"
                },
                "examples": {
                  "paramError": {
                    "$ref": "#/components/examples/MediakitVideoEnhancementParamError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediakitVideoEnhancementErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/MediakitVideoEnhancementParamError"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "tags": [
          "Volcengine MediaKit Video Enhancement"
        ],
        "operationId": "getVolcengineMediakitVideoEnhancementTaskStatus",
        "summary": "Volcengine MediaKit video enhancement task status",
        "description": "Returns the asynchronous task status. On success, `output.urls` contains the enhanced video URL and `usage` contains output duration, frame rate, and resolution data.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "description": "Asynchronous task identifier returned by `/v1/tasks/submit`.",
            "schema": {
              "type": "string"
            },
            "example": "mk-xxxxxxxxxxxx"
          }
        ],
        "responses": {
          "200": {
            "description": "Task status response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediakitVideoEnhancementStatusResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful task",
                    "value": {
                      "output": {
                        "task_id": "mk-xxxxxxxxxxxx",
                        "task_status": "Success",
                        "urls": [
                          "https://your-cdn.example.com/enhanced-output.mp4"
                        ],
                        "submit_time": 1785125529,
                        "finish_time": 1785125946
                      },
                      "usage": {
                        "prompt_tokens": 0,
                        "completion_tokens": 0,
                        "total_tokens": 0,
                        "duration": 15,
                        "output_video_duration": 15.2,
                        "output_video_fps": 30,
                        "size": "1920x1080"
                      },
                      "request_id": "req_xxxxxxxxxxxxx"
                    }
                  },
                  "failure": {
                    "summary": "Failed task",
                    "value": {
                      "output": {
                        "task_id": "mk-xxxxxxxxxxxx",
                        "task_status": "Failure",
                        "submit_time": 1785125529,
                        "finish_time": 1785125540,
                        "error_message": "task failed"
                      },
                      "usage": {
                        "prompt_tokens": 0,
                        "completion_tokens": 0,
                        "total_tokens": 0
                      },
                      "request_id": "req_xxxxxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid task identifier or request parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediakitVideoEnhancementErrorResponse"
                },
                "examples": {
                  "paramError": {
                    "$ref": "#/components/examples/MediakitVideoEnhancementParamError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediakitVideoEnhancementErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/MediakitVideoEnhancementParamError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "Send `Authorization: Bearer {your_api_key}` in the request headers."
      }
    },
    "schemas": {
      "MediakitVideoEnhancementSubmitRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "ai-mediakit-video-enhancement-std",
            "description": "Model name. This schema is pinned to `ai-mediakit-video-enhancement-std`."
          },
          "input": {
            "$ref": "#/components/schemas/MediakitVideoEnhancementInput"
          },
          "parameters": {
            "$ref": "#/components/schemas/MediakitVideoEnhancementParameters"
          }
        }
      },
      "MediakitVideoEnhancementInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "video_url"
        ],
        "properties": {
          "video_url": {
            "type": "string",
            "format": "uri",
            "pattern": "^https?://",
            "description": "Public HTTP/HTTPS URL of the source video to enhance."
          }
        }
      },
      "MediakitVideoEnhancementParameters": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "tool_version": {
            "type": "string",
            "default": "standard",
            "enum": [
              "standard"
            ],
            "description": "Tool version. Only `standard` is supported."
          },
          "scene": {
            "type": "string",
            "enum": [
              "common",
              "ugc",
              "short_series",
              "aigc",
              "old_film"
            ],
            "description": "Enhancement scene. Only effective when `tool_version` is `standard`.\n"
          },
          "enhance_style": {
            "type": "string",
            "enum": [
              "hd",
              "natural"
            ],
            "description": "Enhancement style."
          },
          "resolution": {
            "type": "string",
            "enum": [
              "240p",
              "360p",
              "480p",
              "540p",
              "720p",
              "1080p",
              "2k",
              "4k",
              "6k",
              "8k"
            ],
            "description": "Target output resolution. Mutually exclusive with `resolution_limit`."
          },
          "resolution_limit": {
            "type": "integer",
            "minimum": 128,
            "maximum": 4320,
            "description": "Target output resolution limit (shortest edge in pixels). Mutually exclusive with `resolution`.\nMust be between 128 and 4320.\n"
          },
          "bitrate_level": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "description": "Target bitrate level."
          },
          "bitrate": {
            "type": "integer",
            "minimum": 10,
            "maximum": 150000,
            "description": "Target bitrate in kbps. Must be between 10 and 150000."
          },
          "fps": {
            "type": "number",
            "minimum": 15,
            "maximum": 120,
            "description": "Target output frame rate. Must be between 15 and 120."
          },
          "bit_depth": {
            "type": "integer",
            "enum": [
              8,
              10,
              12,
              16
            ],
            "description": "Output bit depth in bits. Valid values depend on `codec`:\n- `h264`: 8\n- `h265`: 8, 10, 12\n- `prores`: 10\n- `ffv1`: 16\n- `exr`: 16\n"
          },
          "codec": {
            "type": "string",
            "enum": [
              "h264",
              "h265",
              "prores",
              "ffv1",
              "exr"
            ],
            "description": "Output video codec."
          }
        }
      },
      "MediakitVideoEnhancementSubmitResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output",
          "request_id"
        ],
        "properties": {
          "output": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "task_id"
            ],
            "properties": {
              "task_id": {
                "type": "string",
                "description": "Unique asynchronous task identifier."
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier."
          }
        }
      },
      "MediakitVideoEnhancementStatusResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output",
          "request_id"
        ],
        "properties": {
          "output": {
            "$ref": "#/components/schemas/MediakitVideoEnhancementStatusOutput"
          },
          "usage": {
            "$ref": "#/components/schemas/MediakitVideoEnhancementUsage"
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier."
          }
        }
      },
      "MediakitVideoEnhancementStatusOutput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "task_id",
          "task_status"
        ],
        "properties": {
          "task_id": {
            "type": "string",
            "description": "Unique asynchronous task identifier."
          },
          "task_status": {
            "$ref": "#/components/schemas/MediakitVideoEnhancementTaskStatus"
          },
          "urls": {
            "type": "array",
            "description": "Enhanced video URLs returned when the task succeeds.",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "submit_time": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp in seconds when the task was submitted."
          },
          "finish_time": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp in seconds when the task completed."
          },
          "error_message": {
            "type": "string",
            "description": "Error message returned when the task fails."
          }
        }
      },
      "MediakitVideoEnhancementTaskStatus": {
        "type": "string",
        "description": "Asynchronous task status.",
        "enum": [
          "Pending",
          "Running",
          "Success",
          "Failure",
          "Expired",
          "Cancelled",
          "Unknown"
        ]
      },
      "MediakitVideoEnhancementUsage": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "prompt_tokens": {
            "type": "integer"
          },
          "completion_tokens": {
            "type": "integer"
          },
          "total_tokens": {
            "type": "integer"
          },
          "duration": {
            "type": "integer",
            "description": "Output video duration rounded to the nearest second."
          },
          "output_video_duration": {
            "type": "number",
            "description": "Output video duration in seconds."
          },
          "output_video_fps": {
            "type": "integer",
            "description": "Output video frame rate."
          },
          "size": {
            "type": "string",
            "description": "Output video resolution, e.g. `1920x1080`."
          }
        }
      },
      "MediakitVideoEnhancementErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/MediakitVideoEnhancementErrorObject"
          }
        }
      },
      "MediakitVideoEnhancementErrorObject": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "message",
          "type"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message."
          },
          "type": {
            "type": "string",
            "description": "Error type."
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Error code."
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "description": "Related request parameter, if any."
          }
        }
      }
    },
    "examples": {
      "MediakitVideoEnhancementParamError": {
        "summary": "Parameter error",
        "value": {
          "error": {
            "message": "video_url is required for mediakit enhance-video",
            "type": "invalid_request_error",
            "code": "param_error",
            "param": "input.video_url"
          }
        }
      }
    }
  }
}
```