media_upload
Upload 1-50 files (Base64 or local file_path, stdio only) to object storage and return presigned URLs.
Use the URLs wherever a tool needs a media URL (e.g. Seedance video references, which are URL-only). Items fail independently: check failed and items[].error. Requires background execution (ark_job_submit).
| Requirement | Value |
|---|---|
| Registration | Requires the selected object-storage backend: OBJECT_STORAGE_BACKEND=tos (default) with TOS_ACCESS_KEY, TOS_SECRET_KEY and TOS_BUCKET; or OBJECT_STORAGE_BACKEND=s3 with S3_ACCESS_KEY, S3_SECRET_KEY and S3_BUCKET. |
| Execution | Background required |
| Required permission | media:upload |
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 media_upload 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.
Match the input fields below and the full JSON Schema. See the worked examples for this capability and Background Execution for job/result handling.
Inputs
Section titled “Inputs”The MCP arguments object wraps these fields as {"input": {...}}.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
expires_in_seconds |
integer or null | No | Presigned URL validity in seconds for every item; defaults to the server presign TTL. Use >= 3600 for URLs destined for vod_* tools, which fetch asynchronously.; Default: null |
items |
array of MediaUploadItem | Yes | 1-50 files to upload.; minItems: 1; maxItems: 50 |
max_concurrent |
integer | No | Concurrent uploads.; minimum: 1; maximum: 8; Default: 4 |
Outputs
Section titled “Outputs”| Field | Type | Required | Description and constraints |
|---|---|---|---|
failed |
integer | Yes | Number of items that failed; see items[].error. |
items |
array of MediaUploadItemResult | Yes | Per-item results in request order. |
succeeded |
integer | Yes | Number of items uploaded. |
total_bytes |
integer | Yes | Total bytes uploaded across successful items. |
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.
MediaUploadInput
| Field | Type | Required | Description and constraints |
|---|---|---|---|
expires_in_seconds |
integer or null | No | Presigned URL validity in seconds for every item; defaults to the server presign TTL. Use >= 3600 for URLs destined for vod_* tools, which fetch asynchronously.; Default: null |
items |
array of MediaUploadItem | Yes | 1-50 files to upload.; minItems: 1; maxItems: 50 |
max_concurrent |
integer | No | Concurrent uploads.; minimum: 1; maximum: 8; Default: 4 |
MediaUploadItem
| Field | Type | Required | Description and constraints |
|---|---|---|---|
data |
string or null | No | Base64-encoded bytes. Exactly one of data or file_path.; Default: null |
file_path |
string or null | No | Absolute local file path (stdio only). Exactly one of data or file_path.; Default: null |
key_prefix |
string or null | No | Object key prefix, default ‘references’. Only alphanumerics, ’-’, ’_’, ’/’.; Default: null |
media_type |
“image”, “audio”, “video” | Yes | Media category used for validation. |
mime_type |
string or null | No | MIME type (e.g. image/png). Inferred from file_path when omitted; required with data.; Default: null |
Complete JSON Schemas
Section titled “Complete JSON Schemas”Input schema, including the MCP wrapper
{ "$defs": { "MediaUploadInput": { "description": "Input model for ``media_upload``.", "properties": { "expires_in_seconds": { "anyOf": [ { "maximum": 604800, "minimum": 60, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Presigned URL validity in seconds for every item; defaults to the server presign TTL. Use >= 3600 for URLs destined for vod_* tools, which fetch asynchronously." }, "items": { "description": "1-50 files to upload.", "items": { "$ref": "#/$defs/MediaUploadItem" }, "maxItems": 50, "minItems": 1, "type": "array" }, "max_concurrent": { "default": 4, "description": "Concurrent uploads.", "maximum": 8, "minimum": 1, "type": "integer" } }, "required": [ "items" ], "type": "object" }, "MediaUploadItem": { "description": "One file to upload.", "properties": { "data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Base64-encoded bytes. Exactly one of data or file_path." }, "file_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Absolute local file path (stdio only). Exactly one of data or file_path." }, "key_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Object key prefix, default 'references'. Only alphanumerics, '-', '_', '/'." }, "media_type": { "description": "Media category used for validation.", "enum": [ "image", "audio", "video" ], "type": "string" }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "MIME type (e.g. image/png). Inferred from file_path when omitted; required with data." } }, "required": [ "media_type" ], "type": "object" } }, "additionalProperties": false, "properties": { "input": { "$ref": "#/$defs/MediaUploadInput" } }, "required": [ "input" ], "type": "object"}Output schema, including nested definitions
{ "$defs": { "MediaUploadItemResult": { "description": "Per-item upload result.", "properties": { "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Uploaded byte count.", "title": "Bytes" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Failure reason; null on success.", "title": "Error" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 expiry of url.", "title": "Expires At" }, "file_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The item's file_path as given.", "title": "File Path" }, "index": { "description": "0-based position in the request.", "title": "Index", "type": "integer" }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "MIME type used for the upload.", "title": "Mime Type" }, "object_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Object key, reusable with media_presign and ark_asset_create.", "title": "Object Key" }, "retryable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether retrying the upload may succeed; null on success.", "title": "Retryable" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Presigned HTTPS GET URL; null if the item failed.", "title": "Url" } }, "required": [ "index" ], "title": "MediaUploadItemResult", "type": "object" } }, "description": "Output model for ``media_upload``.", "properties": { "failed": { "description": "Number of items that failed; see items[].error.", "title": "Failed", "type": "integer" }, "items": { "description": "Per-item results in request order.", "items": { "$ref": "#/$defs/MediaUploadItemResult" }, "title": "Items", "type": "array" }, "succeeded": { "description": "Number of items uploaded.", "title": "Succeeded", "type": "integer" }, "total_bytes": { "description": "Total bytes uploaded across successful items.", "title": "Total Bytes", "type": "integer" } }, "required": [ "items", "succeeded", "failed", "total_bytes" ], "title": "MediaUploadOutput", "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.