API Reference

Gitruck Cloud public APIs share a consistent HTTP + JSON design across user info, file management, task management, and media processing. This page summarizes the conventions that apply to the whole API surface.

Base Information

Item	Value
Base URL	`https://api.ai-mcn.tv:10000`
Protocol	HTTPS
Data Format	JSON, except file upload which uses `multipart/form-data`
Authentication	Raw API key passed in the `Authorization` header

Authentication Rule

Every business API expects:

Authorization: YOUR_API_KEY

⚠️ Warning: The current backend does not parse a Bearer prefix. If you send Authorization: Bearer YOUR_API_KEY, authentication will fail.

Request Conventions

File upload: POST /base/file/upload with multipart/form-data
Most other APIs: application/json
Media processing APIs follow an async task flow: create task, then query task
Time fields are returned as ISO 8601 style strings

Unified Response Shape

{
  "code": 200,
  "msg": "success",
  "data": {}
}

Field	Type	Description
`code`	`number`	Business code. Success is usually `200`
`msg`	`string`	Status message or error detail
`data`	`object` / `string` / `null`	Response payload. Some successful APIs return an empty string

Task Statuses

Status	Description
`created`	Task created but not yet queued
`queued`	Task is in queue
`processing`	Task is running
`completed`	Task finished successfully
`failed`	Task failed
`cancelled`	Task was cancelled

File Lifecycle

Uploaded files are retained for 60 days
Re-uploading the same file can hit deduplication and reuse an existing record
Expired files can be renewed or uploaded again

Media File Limits

Audio and video tasks check the input file before the task is created. If a requirement below is not met, the request returns the matching error code; no task is created and nothing is charged:

Item	Requirement	Error code if not met
File integrity	The file can be parsed and decoded	`6017` / `6021`
Duration	Greater than 0 and no longer than 2 hours	`6019`
Video resolution	Width and height are both 4000 px or less. Common 3840×2160 video is accepted; 4096×2160 exceeds the limit	`6022`
Video frame rate	120 fps or less	`6023`

Some APIs have stricter limits. For example, video super resolution supports videos up to 1 minute, and the raft algorithm in watermark removal supports videos up to 20 minutes. See each API's documentation for details.

Common Error Codes

Error Code	HTTP Status	Description	Resolution
`400`	400	Invalid request parameters or body	Check JSON shape and parameter types
`401`	401	Unauthenticated request	Check the `Authorization` header
`413`	413	Payload too large	Reduce file size or request size
`415`	415	Unsupported Content-Type	Use `application/json` or `multipart/form-data`
`6001`	400	Unsupported file type	Use a supported media extension
`6002`	413	File exceeds size limit	Upload a file within 20 GB
`6004`	404	File not found	Verify the `file_id`
`6006`	404	Task not found	Verify the `task_id`
`6007`	400	Task cannot be cancelled in current state	Only `created` / `queued` tasks can be cancelled
`6013`	400	Missing required parameter	Add the missing field
`6014`	400	File type does not match the task	Use a compatible file type
`6015`	400	Unsupported language code	Use a supported language code
`6016`	400	Invalid task parameter type or value	Check enums and parameter types
`6017`	400	Media file cannot be parsed: the file is corrupted, malformed, or has conflicting metadata	Re-export the file with an editing or transcoding tool and upload it again
`6019`	400	Media duration is 0 or longer than 2 hours	Trim the media and retry
`6021`	400	Media integrity check failed: some positions cannot be decoded, or the end of the file is incomplete	Use another source file, or re-export a complete file and upload it again
`6022`	400	Video resolution exceeds the limit: width or height is greater than 4000 px (video super resolution checks the upscaled resolution)	Scale the video so that width and height are both 4000 px or less, or lower the output multiplier
`6023`	400	Video frame rate exceeds 120 fps	Convert the video to 120 fps or less (such as 60 fps) and upload it again
`6201`	402	Insufficient quota	Purchase quota or recharge
`6202`	402	Insufficient balance	Recharge in the Dashboard
`6502`	401	Authentication failed	Pass the raw API key in the `Authorization` header
`500`	500	Internal server error	Retry later or contact support