vod_enhance_video
Upscale and enhance a public video with BytePlus VOD AI MediaKit.
Defaults to professional tier, 4K, 24 fps. Not retried automatically. An accepted result carries a task_id: poll it with vod_get_task (operation ‘enhance’). Requires background execution (ark_job_submit).
| Requirement | Value |
|---|---|
| Registration | Requires BYTEPLUS_VOD_MEDIAKIT_API_KEY. |
| Execution | Background required |
| Required permission | vod:enhance |
This site lists the full configured capability surface, not the tools enabled on your particular server. Use model discovery and job discovery to check your connection. Credentials are server configuration, never tool arguments.
Ask your connected AI client to use vod_enhance_video for the operation you want.
The client constructs the arguments and handles tool calls. Review its proposed
operation before approving anything billable. For a non-billable introduction,
start with discovery without generation.
Submit through ark_job_submit with tool_name and the complete target arguments, including its inner input object. Poll ark_job_get using the returned Ark job_id, respecting poll_after_ms. Inspect both terminal status and result.is_error; the original output is in result.structured_content. Do not call this tool in the foreground.
Exact MCP call (for developers)
The following is an MCP tool-call envelope, not a shell command. Example media URLs and identifiers must be replaced with your own accessible resources. Seedream and Seedance examples are non-billable dry runs; other provider operations may incur charges.
{ "name": "ark_job_submit", "arguments": { "input": { "tool_name": "vod_enhance_video", "arguments": { "input": { "video_url": "https://example.com/video.mp4" } } } }}An Ark job ID is not a provider task ID. Video and 3D tasks use gen_task_get, VOD tasks use vod_get_task, and avatars use omnihuman_get_task. Save accepted provider task IDs and resume polling instead of submitting a second generation.
Inputs
Section titled “Inputs”The MCP arguments object wraps these fields as {"input": {...}}.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
bitrate |
integer or null | No | Exact average bitrate in kbps; overrides bitrate_level.; Default: null |
bitrate_level |
“low”, “medium”, “high” | No | Target bitrate tier; ignored when bitrate is set.; Default: “high” |
enhance_style |
“hd”, “natural” or null | No | ‘hd’ (provider default) is sharper; ‘natural’ reduces sharpening artifacts. Not supported by ‘fast’.; Default: null |
fps |
number or null | No | Target frames per second; above the source rate interpolates (keep within 4x). Null keeps the source rate.; Default: 24 |
input_duration_seconds |
number or null | No | Source duration in seconds; currently unused (reserved for pricing).; Default: null |
persist |
boolean | No | Copy a directly returned completed output into the durable artifact store (best effort).; Default: true |
project |
string | No | MediaKit project label (case-sensitive).; minLength: 1; maxLength: 128; Default: “default” |
resolution |
“240p”, “360p”, “480p”, “540p”, “720p”, “1080p”, “2k”, “4k”, “6k”, “8k” or null | No | Target resolution level; ‘fast’ tops out at 4k. Mutually exclusive with resolution_limit. Defaults to ‘4k’ when neither is set.; Default: null |
resolution_limit |
integer or null | No | Target short-side pixels, aspect ratio preserved; max 2160 for ‘fast’. Mutually exclusive with resolution.; Default: null |
scene |
“common”, “ugc”, “short_series”, “aigc”, “old_film” | No | Scenario preset; only used when tool_version is ‘standard’.; Default: “common” |
tool_version |
“fast”, “standard”, “professional” | No | ‘fast’: lightweight, fastest (input up to 2K). ‘standard’: balanced, honors ‘scene’. ‘professional’: highest quality, slower and costlier.; Default: “professional” |
video_url |
string | Yes | Public HTTPS source-video URL; private and link-local hosts are rejected.; minLength: 1; format: “uri” |
Outputs
Section titled “Outputs”| Field | Type | Required | Description and constraints |
|---|---|---|---|
estimated_cost_usd |
number or null | No | Always null; cost estimation is not available.; Default: null |
operation |
“enhance”, “transcode”, “separate_audio”, “add_subtitles”, “remove_subtitles” | No | Operation name; pass it to vod_get_task with task_id.; Default: “enhance” |
output_size_bytes |
integer or null | No | Output size in bytes, when returned.; Default: null |
persistence |
“not_applicable”, “not_requested”, “persisted”, “failed” | Yes | Durable persistence outcome, independent of provider success. |
persistence_issue |
VodArtifactPersistenceIssue or null | No | Safe explanation when persistence failed.; Default: null |
provider |
“byteplus-vod-mediakit” | No | Provider surface.; Default: “byteplus-vod-mediakit” |
provider_log_id |
string or null | No | Provider x-tt-logid, when returned.; Default: null |
provider_status |
string or null | No | Raw provider status label, when returned.; Default: null |
request_id |
string or null | No | Provider request ID, when returned.; Default: null |
source_expires_at |
string or null | No | ISO-8601 expiry of source_url, when returned.; Default: null |
source_url |
string or null | No | Expiring provider output URL; absent while a task is still processing.; Default: null |
status |
“accepted”, “succeeded” | Yes | accepted: task queued, poll vod_get_task; succeeded: output returned directly. |
task_id |
string or null | No | Task ID to poll with vod_get_task (operation ‘enhance’).; Default: null |
video |
ArtifactRef or null | No | Durable enhanced-video artifact, when persisted.; Default: null |
Nested Types
Section titled “Nested Types”Field types named above refer to these shared definitions. Optional/null fields, enum choices and bounds are retained in the complete schemas below. Schema validation is followed by runtime capability and security checks.
VodEnhanceVideoInput
| Field | Type | Required | Description and constraints |
|---|---|---|---|
bitrate |
integer or null | No | Exact average bitrate in kbps; overrides bitrate_level.; Default: null |
bitrate_level |
“low”, “medium”, “high” | No | Target bitrate tier; ignored when bitrate is set.; Default: “high” |
enhance_style |
“hd”, “natural” or null | No | ‘hd’ (provider default) is sharper; ‘natural’ reduces sharpening artifacts. Not supported by ‘fast’.; Default: null |
fps |
number or null | No | Target frames per second; above the source rate interpolates (keep within 4x). Null keeps the source rate.; Default: 24 |
input_duration_seconds |
number or null | No | Source duration in seconds; currently unused (reserved for pricing).; Default: null |
persist |
boolean | No | Copy a directly returned completed output into the durable artifact store (best effort).; Default: true |
project |
string | No | MediaKit project label (case-sensitive).; minLength: 1; maxLength: 128; Default: “default” |
resolution |
“240p”, “360p”, “480p”, “540p”, “720p”, “1080p”, “2k”, “4k”, “6k”, “8k” or null | No | Target resolution level; ‘fast’ tops out at 4k. Mutually exclusive with resolution_limit. Defaults to ‘4k’ when neither is set.; Default: null |
resolution_limit |
integer or null | No | Target short-side pixels, aspect ratio preserved; max 2160 for ‘fast’. Mutually exclusive with resolution.; Default: null |
scene |
“common”, “ugc”, “short_series”, “aigc”, “old_film” | No | Scenario preset; only used when tool_version is ‘standard’.; Default: “common” |
tool_version |
“fast”, “standard”, “professional” | No | ‘fast’: lightweight, fastest (input up to 2K). ‘standard’: balanced, honors ‘scene’. ‘professional’: highest quality, slower and costlier.; Default: “professional” |
video_url |
string | Yes | Public HTTPS source-video URL; private and link-local hosts are rejected.; minLength: 1; format: “uri” |
Complete JSON Schemas
Section titled “Complete JSON Schemas”Input schema, including the MCP wrapper
{ "$defs": { "VodEnhanceVideoInput": { "description": "Input for fast, standard, or professional MediaKit video enhancement.", "properties": { "bitrate": { "anyOf": [ { "maximum": 150000, "minimum": 10, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Exact average bitrate in kbps; overrides bitrate_level." }, "bitrate_level": { "default": "high", "description": "Target bitrate tier; ignored when bitrate is set.", "enum": [ "low", "medium", "high" ], "type": "string" }, "enhance_style": { "anyOf": [ { "enum": [ "hd", "natural" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "'hd' (provider default) is sharper; 'natural' reduces sharpening artifacts. Not supported by 'fast'." }, "fps": { "anyOf": [ { "maximum": 120, "minimum": 15, "type": "number" }, { "type": "null" } ], "default": 24, "description": "Target frames per second; above the source rate interpolates (keep within 4x). Null keeps the source rate." }, "input_duration_seconds": { "anyOf": [ { "exclusiveMinimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "description": "Source duration in seconds; currently unused (reserved for pricing)." }, "persist": { "default": true, "description": "Copy a directly returned completed output into the durable artifact store (best effort).", "type": "boolean" }, "project": { "default": "default", "description": "MediaKit project label (case-sensitive).", "maxLength": 128, "minLength": 1, "type": "string" }, "resolution": { "anyOf": [ { "enum": [ "240p", "360p", "480p", "540p", "720p", "1080p", "2k", "4k", "6k", "8k" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Target resolution level; 'fast' tops out at 4k. Mutually exclusive with resolution_limit. Defaults to '4k' when neither is set." }, "resolution_limit": { "anyOf": [ { "maximum": 4320, "minimum": 128, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Target short-side pixels, aspect ratio preserved; max 2160 for 'fast'. Mutually exclusive with resolution." }, "scene": { "default": "common", "description": "Scenario preset; only used when tool_version is 'standard'.", "enum": [ "common", "ugc", "short_series", "aigc", "old_film" ], "type": "string" }, "tool_version": { "default": "professional", "description": "'fast': lightweight, fastest (input up to 2K). 'standard': balanced, honors 'scene'. 'professional': highest quality, slower and costlier.", "enum": [ "fast", "standard", "professional" ], "type": "string" }, "video_url": { "description": "Public HTTPS source-video URL; private and link-local hosts are rejected.", "format": "uri", "minLength": 1, "type": "string" } }, "required": [ "video_url" ], "type": "object" } }, "additionalProperties": false, "properties": { "input": { "$ref": "#/$defs/VodEnhanceVideoInput" } }, "required": [ "input" ], "type": "object"}Output schema, including nested definitions
{ "$defs": { "ArtifactPersistenceIssue": { "description": "Safe explanation for a provider output that could not be persisted.", "properties": { "artifact_limit_bytes": { "description": "Maximum durable artifact size in bytes.", "title": "Artifact Limit Bytes", "type": "integer" }, "code": { "description": "Failure category.", "enum": [ "untrusted_output_host", "output_too_large", "invalid_output_mime", "source_expired", "download_failed", "storage_failed" ], "title": "Code", "type": "string" }, "message": { "description": "Safe failure message (no credentials or URLs).", "title": "Message", "type": "string" }, "retryable": { "description": "Whether retrying persistence later may succeed.", "title": "Retryable", "type": "boolean" }, "source_url_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 expiry of the unpersisted provider URL (the artifact uri).", "title": "Source Url Expires At" } }, "required": [ "code", "message", "retryable", "artifact_limit_bytes" ], "title": "ArtifactPersistenceIssue", "type": "object" }, "ArtifactRef": { "description": "Stable reference to a persisted media artifact.", "properties": { "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Size in bytes.", "title": "Bytes" }, "created_at": { "description": "ISO-8601 timestamp of artifact creation.", "title": "Created At", "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 expiry of the stored artifact.", "title": "Expires At" }, "export_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the requested local copy was not written (the artifact is unaffected).", "title": "Export Error" }, "fallback_data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Base64 output bytes, only with id 'inline-fallback'.", "title": "Fallback Data" }, "id": { "description": "Unique artifact identifier.", "title": "Id", "type": "string" }, "local_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Absolute path of the local copy written for output_path/output_dir.", "title": "Local Path" }, "media_type": { "$ref": "#/$defs/MediaType", "description": "image, audio, video or three_d." }, "mime_type": { "description": "MIME type, e.g. image/png.", "title": "Mime Type", "type": "string" }, "persistence_error": { "anyOf": [ { "$ref": "#/$defs/ArtifactPersistenceIssue" }, { "type": "null" } ], "default": null, "description": "Set when the output was billed but not stored. id is then 'provider-url' (uri is the temporary provider URL; re-persist it with seed_media_persist_url before source_expires_at) or 'inline-fallback' (bytes in fallback_data)." }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "SHA-256 hex digest.", "title": "Sha256" }, "source_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 expiry of the provider URL.", "title": "Source Expires At" }, "uri": { "description": "MCP resource URI (seed-media://artifacts/{id}).", "title": "Uri", "type": "string" } }, "required": [ "id", "uri", "media_type", "mime_type", "created_at" ], "title": "ArtifactRef", "type": "object" }, "MediaType": { "description": "Logical generated-media categories.", "enum": [ "image", "audio", "video", "three_d" ], "title": "MediaType", "type": "string" }, "VodArtifactPersistenceIssue": { "description": "Safe explanation for a provider success that was not persisted.", "properties": { "artifact_limit_bytes": { "description": "Maximum durable artifact size in bytes.", "title": "Artifact Limit Bytes", "type": "integer" }, "code": { "description": "Failure category.", "enum": [ "untrusted_output_host", "output_too_large", "invalid_output_mime", "source_expired", "download_failed", "storage_failed" ], "title": "Code", "type": "string" }, "message": { "description": "Safe failure message (no credentials or URLs).", "title": "Message", "type": "string" }, "retryable": { "description": "Whether retrying persistence later may succeed.", "title": "Retryable", "type": "boolean" }, "source_url_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 expiry of the unpersisted provider URL (the artifact uri).", "title": "Source Url Expires At" } }, "required": [ "code", "message", "retryable", "artifact_limit_bytes" ], "title": "VodArtifactPersistenceIssue", "type": "object" } }, "description": "Normalized successful MediaKit enhancement result.", "properties": { "estimated_cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Always null; cost estimation is not available.", "title": "Estimated Cost Usd" }, "operation": { "default": "enhance", "description": "Operation name; pass it to vod_get_task with task_id.", "enum": [ "enhance", "transcode", "separate_audio", "add_subtitles", "remove_subtitles" ], "title": "Operation", "type": "string" }, "output_size_bytes": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Output size in bytes, when returned.", "title": "Output Size Bytes" }, "persistence": { "description": "Durable persistence outcome, independent of provider success.", "enum": [ "not_applicable", "not_requested", "persisted", "failed" ], "title": "Persistence", "type": "string" }, "persistence_issue": { "anyOf": [ { "$ref": "#/$defs/VodArtifactPersistenceIssue" }, { "type": "null" } ], "default": null, "description": "Safe explanation when persistence failed." }, "provider": { "const": "byteplus-vod-mediakit", "default": "byteplus-vod-mediakit", "description": "Provider surface.", "title": "Provider", "type": "string" }, "provider_log_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider x-tt-logid, when returned.", "title": "Provider Log Id" }, "provider_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Raw provider status label, when returned.", "title": "Provider Status" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider request ID, when returned.", "title": "Request Id" }, "source_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 expiry of source_url, when returned.", "title": "Source Expires At" }, "source_url": { "anyOf": [ { "format": "uri", "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Expiring provider output URL; absent while a task is still processing.", "title": "Source Url" }, "status": { "description": "accepted: task queued, poll vod_get_task; succeeded: output returned directly.", "enum": [ "accepted", "succeeded" ], "title": "Status", "type": "string" }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Task ID to poll with vod_get_task (operation 'enhance').", "title": "Task Id" }, "video": { "anyOf": [ { "$ref": "#/$defs/ArtifactRef" }, { "type": "null" } ], "default": null, "description": "Durable enhanced-video artifact, when persisted." } }, "required": [ "status", "persistence" ], "title": "VodEnhanceVideoOutput", "type": "object"}Troubleshooting
Section titled “Troubleshooting”- Missing tool: check provider credentials and feature flags, then restart the connection.
- Invalid arguments: keep the correct wrapper and follow current model limits from discovery. A valid schema alone does not prove the chosen model supports the combination.
- A job completes with an error: inspect the original tool result, not only the outer job status. Never automatically resubmit potentially billable work.
- Local output writes from jobs require server-configured
OUTPUT_ROOTS; HTTP cannot write to a client’s local disk.
See configuration, background execution, and artifact delivery.