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

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
`6019`	400	Invalid or unsupported media duration	Trim the media and retry
`6022`	400	Video resolution exceeds limit	Lower the input resolution or output multiplier
`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