Video Download API Documentation

Submit asynchronous video download tasks, check remaining traffic, list tasks, and redirect to completed download results.

Authentication

All API requests require your API token in the HTTP header.

Header: x-api-key: YOUR_API_KEY
Bearer auth is also supported: Authorization: Bearer YOUR_API_KEY
Generate or view API token

Requests include basic anti-spam protection. Avoid sending duplicate requests too quickly.

POST https://iphtml.com/v1/download/video

1. Create Download Task

Create an asynchronous video download task. The response returns a local task_id; use it to query or download the result later.

Request Parameters

Parameter	Type	Required	Default	Description
`platform`	String	Yes	-	Enabled download platform from `serp_video_product`. Currently supports values such as `youtube` and `tiktok`.
`url`	String(500)	Yes	-	Video URL. YouTube must use `youtube.com` or `youtu.be`; TikTok must use `tiktok.com`.
`quality`	String	No	1080P	One of `360P`, `480P`, `720P`, `1080P`.
`format`	String	No	mp4	One of `mp4`, `webm`.
`postbackurl`	String(255)	No	-	User callback URL. When the task finishes, the system sends a JSON notification to this URL.

cURL Example

curl -X POST "https://iphtml.com/v1/download/video" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-api-key: YOUR_API_KEY" \
  -d "platform=youtube" \
  -d "url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DJeEEL6TESTw" \
  -d "quality=720P" \
  -d "format=mp4" \
  -d "postbackurl=https://example.com/video-callback"

Success Response

{
  "retCode": 200,
  "retMsg": "Task queued successfully",
  "task_id": "52388bccd4d3d2b3934bd265cdf71845",
  "id": 123,
  "remaining": 19.99,
  "unit": "GB"
}

GET https://iphtml.com/v1/video

2. Download Completed Result

Redirects to the completed task's downloadable file URL. If the task is not completed, a JSON error is returned.

Query Parameters

Parameter	Type	Required	Description
`task_id`	String	Yes	The task ID returned by the Create Download Task endpoint.

Example

curl -L "https://iphtml.com/v1/video?task_id=52388bccd4d3d2b3934bd265cdf71845" \
  -H "x-api-key: YOUR_API_KEY"

GET https://iphtml.com/v1/video/task

3. Check Task Progress

Query the current execution progress and status of the specified task.

Request Parameters

Parameter	Type	Required	Description
`task_id`	String	Yes	The `task_id` returned from the /download/index endpoint (task_no)

Response Parameters

Parameter	Type	Description
`retCode`	Integer	API request status code, 200 means success
`retMsg`	String	Status message
`status`	String	Task execution status: - processing - success - failed
`success`	Boolean	Whether the task completed successfully
`video_path`	String	Video download URL (only present when status is success)
`error`	String	Error message, empty if no error

Success Response Example

{
    "retCode": 200,
    "retMsg": "Success",
    "status": "completed",
    "success": true,
    "video_path": "http://www.iphtml.org/download/getlink?paremeter=cHjdwjGkdqnxnzMN6UWy6B19-6tZQOgfX3ZNgwGDJK3zRU41xCXX-9V8I2GWvDQ1-UkwRlOH6ujqnH0KkN2ep1Lmjd34GcJB82thkTWeraB1JYuCj1m8cAH3UTGNgbZ4nLB_kSdk4-FkLBGCr1laXw"
}

POST https://iphtml.com/v1/video/list

4. List Download Tasks

Returns paginated download task history for the authenticated user.

Request Parameters

Parameter	Type	Required	Default	Description
`page`	Integer	No	1	Page number.
`page_size`	Integer	No	20	Items per page, max 100.

Response

{
  "retCode": 200,
  "retMsg": "Success",
  "orderList": [
    {
      "task_id": "52388bccd4d3d2b3934bd265cdf71845",
      "remote_task_id": "395c49e4b09841d7a7660a218dc4738b",
      "url": "https://www.youtube.com/watch?v=JeEEL6TESTw",
      "engine": "youtube",
      "format": "mp4",
      "quality": "720P",
      "status": "completed",
      "traffic_used": 2800399,
      "result_code": 200,
      "filename": "download-20260428164651.mp4",
      "result_link": "http://92.118.112.223:8080/download/...",
      "error": "",
      "create_time": 1777970811,
      "updated_at": 1777970811
    }
  ],
  "page": 1,
  "page_size": 20
}

POST User postbackurl

5. User Callback Notification

If postbackurl is provided when creating a task, the system sends a POST JSON notification after the task reaches a final state.

Callback Payload

Parameter	Type	Required	Description
`task_id`	String	Yes	Unique task identifier
`success`	Boolean	Yes	Whether the task completed successfully
`status`	String	Yes	Task final status: • `completed` - Download successful • `failed` - Download failed
`video_path`	String	Conditional	Video download URL (only present when `success = true`)
`error`	String	Conditional	Error message (only present when `success = false`)

{
  "task_id": "52388bccd4d3d2b3934bd265cdf71845",
  "success": true,
  "status": "completed",
  "video_path": "http://www.iphtml.org/download/getlink?paremeter=cHjdwjGkdqnxnzMN6UWy6B19-6tZQOgfX3ZNgwGDJK3zRU41xCXX-9V8I2GWvDQ1-UkwRlOH6ujqnH0KkN2ep1Lmjd34GcJB82thkTWeraB1JYuCj1m8cAH3UTGNgbZ4nLB_kSdk4-FkLBGCr1laXw"
}

Failed Callback Payload

{
  "task_id": "52388bccd4d3d2b3934bd265cdf71845",
  "success": false,
  "status": "failed",
  "error": "Download failed, please try again later."
}

Use GET https://iphtml.com/v1/video?task_id=<TASK_ID> to retrieve the completed file after receiving a successful callback.

Error Codes

retCode	Meaning
`10001`	Request method error or missing API key.
`10002`	Missing required parameter such as `url` or `task_id`.
`10010`	Invalid search engine / platform.
`10011`	Invalid quality.
`10012`	Invalid format.
`10015`	No active plan available.
`10016`	URL domain does not match selected platform.
`10099`	Internal server error.