# 火山引擎 MediaKit 视频增强任务状态

> 视频生成

查询异步任务状态。任务成功时，`output.urls` 包含增强后的视频地址，`usage` 包含输出时长、帧率和分辨率等用量信息。

## 请求地址

`GET https://api.modelverse.cn/v1/tasks/status`

## 请求参数

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| task_id | query | string | Yes | `/v1/tasks/submit` 返回的异步任务标识。 |

## 响应

- **200** — 任务状态响应。
- **400** — 任务标识或请求参数无效。
- **default** — 错误响应。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "火山引擎 MediaKit 视频增强 API",
    "version": "1.0.0",
    "description": "本文档描述 ModelVerse 上 `ai-mediakit-video-enhancement-std` 异步视频增强服务的接口。\n接口路径为 `POST /v1/tasks/submit` 与 `GET /v1/tasks/status`。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "本文档使用的 ModelVerse API 端点。"
    }
  ],
  "tags": [
    {
      "name": "火山引擎 MediaKit 视频增强",
      "description": "火山引擎 MediaKit 异步视频增强。"
    }
  ],
  "paths": {
    "/v1/tasks/submit": {
      "post": {
        "tags": [
          "火山引擎 MediaKit 视频增强"
        ],
        "operationId": "submitVolcengineMediakitVideoEnhancementTask",
        "summary": "火山引擎 MediaKit 视频增强",
        "description": "提交一个异步视频增强任务。需要通过 `input.video_url` 提供待增强视频。\n\n`parameters` 为可选参数。不传入时，上游服务使用自身默认值。若设置 `tool_version`，仅支持 `standard`。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MediakitVideoEnhancementSubmitRequest"
              },
              "examples": {
                "simple": {
                  "summary": "直接通过 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": "任务提交成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediakitVideoEnhancementSubmitResponse"
                },
                "examples": {
                  "submitted": {
                    "summary": "已提交任务",
                    "value": {
                      "output": {
                        "task_id": "mk-xxxxxxxxxxxx"
                      },
                      "request_id": "req_xxxxxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数或输入组合无效。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediakitVideoEnhancementErrorResponse"
                },
                "examples": {
                  "paramError": {
                    "$ref": "#/components/examples/MediakitVideoEnhancementParamError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediakitVideoEnhancementErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/MediakitVideoEnhancementParamError"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "tags": [
          "火山引擎 MediaKit 视频增强"
        ],
        "operationId": "getVolcengineMediakitVideoEnhancementTaskStatus",
        "summary": "火山引擎 MediaKit 视频增强任务状态",
        "description": "查询异步任务状态。任务成功时，`output.urls` 包含增强后的视频地址，`usage` 包含输出时长、帧率和分辨率等用量信息。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "description": "`/v1/tasks/submit` 返回的异步任务标识。",
            "schema": {
              "type": "string"
            },
            "example": "mk-xxxxxxxxxxxx"
          }
        ],
        "responses": {
          "200": {
            "description": "任务状态响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediakitVideoEnhancementStatusResponse"
                },
                "examples": {
                  "success": {
                    "summary": "成功任务",
                    "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": "失败任务",
                    "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": "任务标识或请求参数无效。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediakitVideoEnhancementErrorResponse"
                },
                "examples": {
                  "paramError": {
                    "$ref": "#/components/examples/MediakitVideoEnhancementParamError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "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": "在请求头中发送 `Authorization: Bearer {your_api_key}`。"
      }
    },
    "schemas": {
      "MediakitVideoEnhancementSubmitRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "ai-mediakit-video-enhancement-std",
            "description": "模型名称。本文档固定为 `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": "待增强视频的公开 HTTP/HTTPS URL。"
          }
        }
      },
      "MediakitVideoEnhancementParameters": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "tool_version": {
            "type": "string",
            "default": "standard",
            "enum": [
              "standard"
            ],
            "description": "工具版本。仅支持 `standard`。"
          },
          "scene": {
            "type": "string",
            "enum": [
              "common",
              "ugc",
              "short_series",
              "aigc",
              "old_film"
            ],
            "description": "画质增强场景。仅在 `tool_version` 为 `standard` 时生效。\n"
          },
          "enhance_style": {
            "type": "string",
            "enum": [
              "hd",
              "natural"
            ],
            "description": "画质增强风格。"
          },
          "resolution": {
            "type": "string",
            "enum": [
              "240p",
              "360p",
              "480p",
              "540p",
              "720p",
              "1080p",
              "2k",
              "4k",
              "6k",
              "8k"
            ],
            "description": "目标输出分辨率。与 `resolution_limit` 互斥。"
          },
          "resolution_limit": {
            "type": "integer",
            "minimum": 128,
            "maximum": 4320,
            "description": "目标输出分辨率限制（短边像素数）。与 `resolution` 互斥。\n取值范围为 128 到 4320。\n"
          },
          "bitrate_level": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "description": "目标码率级别。"
          },
          "bitrate": {
            "type": "integer",
            "minimum": 10,
            "maximum": 150000,
            "description": "目标码率，单位为 kbps。取值范围为 10 到 150000。"
          },
          "fps": {
            "type": "number",
            "minimum": 15,
            "maximum": 120,
            "description": "目标输出帧率。取值范围为 15 到 120。"
          },
          "bit_depth": {
            "type": "integer",
            "enum": [
              8,
              10,
              12,
              16
            ],
            "description": "输出位深（比特）。有效值取决于 `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": "输出视频编码格式。"
          }
        }
      },
      "MediakitVideoEnhancementSubmitResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output",
          "request_id"
        ],
        "properties": {
          "output": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "task_id"
            ],
            "properties": {
              "task_id": {
                "type": "string",
                "description": "唯一的异步任务标识。"
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "唯一的请求标识。"
          }
        }
      },
      "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": "唯一的请求标识。"
          }
        }
      },
      "MediakitVideoEnhancementStatusOutput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "task_id",
          "task_status"
        ],
        "properties": {
          "task_id": {
            "type": "string",
            "description": "唯一的异步任务标识。"
          },
          "task_status": {
            "$ref": "#/components/schemas/MediakitVideoEnhancementTaskStatus"
          },
          "urls": {
            "type": "array",
            "description": "任务成功时返回的增强后视频 URL 列表。",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "submit_time": {
            "type": "integer",
            "format": "int64",
            "description": "任务提交时的 Unix 时间戳，单位为秒。"
          },
          "finish_time": {
            "type": "integer",
            "format": "int64",
            "description": "任务完成时的 Unix 时间戳，单位为秒。"
          },
          "error_message": {
            "type": "string",
            "description": "任务失败时返回的错误信息。"
          }
        }
      },
      "MediakitVideoEnhancementTaskStatus": {
        "type": "string",
        "description": "异步任务状态。",
        "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": {
            "type": "number",
            "description": "输出视频时长，单位为秒。"
          },
          "output_video_fps": {
            "type": "integer",
            "description": "输出视频帧率。"
          },
          "size": {
            "type": "string",
            "description": "输出视频分辨率，例如 `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": "错误信息。"
          },
          "type": {
            "type": "string",
            "description": "错误类型。"
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "description": "错误码。"
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "description": "相关的请求参数，如有。"
          }
        }
      }
    },
    "examples": {
      "MediakitVideoEnhancementParamError": {
        "summary": "参数错误",
        "value": {
          "error": {
            "message": "video_url is required for mediakit enhance-video",
            "type": "invalid_request_error",
            "code": "param_error",
            "param": "input.video_url"
          }
        }
      }
    }
  }
}
```