POST /api/v1/upscale — 按视频时长扣除积分，并开始将视频提升到 1080p、2K 或 4K。

POST https://videoupscaler.co/api/v1/upscale

发起一次画质增强，并返回新建的任务。我们会先下载视频、从文件中读取真实时长并据此扣除积分，然后才开始处理。你无需自己传入时长。

请求

请求头

请求头	必填	说明
`Authorization`	是	`Bearer <your API key>`
`Content-Type`	是	`application/json`
`Idempotency-Key`	建议	任意 1–255 个可打印 ASCII 字符组成的字符串。使用相同的 Key 重试永远不会重复扣费。参见幂等性。

请求体

字段	类型	必填	说明
`video_url`	string	是	视频的公开 `http(s)` URL，或 /uploads 返回的 `video_url`。
`resolution`	string	是	`1080p`、`2k` 或 `4k`。

视频要求

格式：MP4、MOV 和 WebM。
时长：不超过 600 秒。
大小：远程 video_url 不超过 500MB，通过 /uploads 上传的不超过 100MB。
video_url 所在的服务器必须能响应普通的 GET 请求，直接返回文件并带有 Content-Length 响应头。S3、R2 或 Google Cloud Storage 的签名链接都可以；YouTube、Google Drive 预览这类分享页面则不行。
缺少总时长信息的分片 MP4（Fragmented MP4）会被拒绝，请先重新编码为常规 MP4。
WebM 文件的文件头中必须包含时长。浏览器录制（MediaRecorder）的文件通常没有，请先重新编码。

示例

curl https://videoupscaler.co/api/v1/upscale \
  -H "Authorization: Bearer $VIDEOUPSCALER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234" \
  -d '{"video_url": "https://example.com/clip.mp4", "resolution": "2k"}'

const res = await fetch('https://videoupscaler.co/api/v1/upscale', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDEOUPSCALER_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1234',
  },
  body: JSON.stringify({ video_url: 'https://example.com/clip.mp4', resolution: '2k' }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const task = await res.json();

res = requests.post(
    "https://videoupscaler.co/api/v1/upscale",
    headers={
        "Authorization": f"Bearer {os.environ['VIDEOUPSCALER_API_KEY']}",
        "Idempotency-Key": "order-1234",
    },
    json={"video_url": "https://example.com/clip.mp4", "resolution": "2k"},
    timeout=300,
)
res.raise_for_status()
task = res.json()

响应

返回 201 Created 及任务对象：

{
  "id": "0b6f3c1e-8a52-5d1e-9c43-3f1d2e7a9b10",
  "status": "processing",
  "resolution": "2k",
  "video_url": "https://example.com/clip.mp4",
  "duration_seconds": 12.4,
  "processed_seconds": 12.4,
  "credits_charged": 26,
  "watermark": false,
  "output_url": null,
  "thumbnail_url": null,
  "error": null,
  "created_at": "2026-09-30T08:00:00.000Z",
  "updated_at": "2026-09-30T08:00:02.000Z"
}

然后轮询任务直到状态变为 completed。

该请求会先下载视频再返回响应，远程文件较大时可能需要一些时间。请把超时时间设为至少 5 分钟。

幂等性

每个请求都带上 Idempotency-Key，并在超时或网络错误后重试时复用同一个 Key：

相同的 Key 搭配相同的 video_url 和 resolution，会以 200 OK 返回原来的任务，不会再次扣费。
相同的 Key 搭配不同的 video_url 或 resolution，返回 409 idempotency_conflict。
不带该请求头时，每个请求都会新建任务并扣费。

计费

价格 = 视频时长（按整秒向上取整）× 对应分辨率的费率。参见积分与价格。一段 12.4 秒的视频增强到 2K 需要 13 × 2 = 26 积分。

如果任务失败，积分会自动退还，任务状态变为 failed。

错误

状态码	错误码	触发条件
`400`	`invalid_request`	`video_url`、`resolution` 或 `Idempotency-Key` 缺失或无效
`401`	`unauthorized`	API 密钥缺失或无效
`403`	`paid_plan_required`	账号从未购买过积分或订阅
`402`	`insufficient_credits`	余额不足以处理该视频
`409`	`idempotency_conflict`	该 `Idempotency-Key` 已用于不同参数的请求
`413`	`file_too_large`	视频大于 500MB
`422`	`video_fetch_failed`	无法下载 `video_url`
`422`	`unsupported_video`	不是可读取的 MP4、MOV 或 WebM，或缺少时长信息
`422`	`video_too_long`	视频时长超过 600 秒
`422`	`video_not_found`	上传所得的 `video_url` 下没有文件（上传未完成）
`504`	`upstream_timeout`	下载 `video_url` 超过 4 分钟

错误格式参见错误。

POST https://videoupscaler.co/api/v1/upscale

发起一次画质增强，并返回新建的任务。我们会先下载视频、从文件中读取真实时长并据此扣除积分，然后才开始处理。你无需自己传入时长。

请求

请求头

请求头	必填	说明
`Authorization`	是	`Bearer <your API key>`
`Content-Type`	是	`application/json`
`Idempotency-Key`	建议	任意 1–255 个可打印 ASCII 字符组成的字符串。使用相同的 Key 重试永远不会重复扣费。参见幂等性。

请求体

字段	类型	必填	说明
`video_url`	string	是	视频的公开 `http(s)` URL，或 /uploads 返回的 `video_url`。
`resolution`	string	是	`1080p`、`2k` 或 `4k`。

视频要求

格式：MP4、MOV 和 WebM。
时长：不超过 600 秒。
大小：远程 video_url 不超过 500MB，通过 /uploads 上传的不超过 100MB。
video_url 所在的服务器必须能响应普通的 GET 请求，直接返回文件并带有 Content-Length 响应头。S3、R2 或 Google Cloud Storage 的签名链接都可以；YouTube、Google Drive 预览这类分享页面则不行。
缺少总时长信息的分片 MP4（Fragmented MP4）会被拒绝，请先重新编码为常规 MP4。
WebM 文件的文件头中必须包含时长。浏览器录制（MediaRecorder）的文件通常没有，请先重新编码。

示例

curl https://videoupscaler.co/api/v1/upscale \
  -H "Authorization: Bearer $VIDEOUPSCALER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234" \
  -d '{"video_url": "https://example.com/clip.mp4", "resolution": "2k"}'

const res = await fetch('https://videoupscaler.co/api/v1/upscale', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDEOUPSCALER_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1234',
  },
  body: JSON.stringify({ video_url: 'https://example.com/clip.mp4', resolution: '2k' }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const task = await res.json();

res = requests.post(
    "https://videoupscaler.co/api/v1/upscale",
    headers={
        "Authorization": f"Bearer {os.environ['VIDEOUPSCALER_API_KEY']}",
        "Idempotency-Key": "order-1234",
    },
    json={"video_url": "https://example.com/clip.mp4", "resolution": "2k"},
    timeout=300,
)
res.raise_for_status()
task = res.json()

响应

返回 201 Created 及任务对象：

{
  "id": "0b6f3c1e-8a52-5d1e-9c43-3f1d2e7a9b10",
  "status": "processing",
  "resolution": "2k",
  "video_url": "https://example.com/clip.mp4",
  "duration_seconds": 12.4,
  "processed_seconds": 12.4,
  "credits_charged": 26,
  "watermark": false,
  "output_url": null,
  "thumbnail_url": null,
  "error": null,
  "created_at": "2026-09-30T08:00:00.000Z",
  "updated_at": "2026-09-30T08:00:02.000Z"
}

然后轮询任务直到状态变为 completed。

该请求会先下载视频再返回响应，远程文件较大时可能需要一些时间。请把超时时间设为至少 5 分钟。

幂等性

每个请求都带上 Idempotency-Key，并在超时或网络错误后重试时复用同一个 Key：

相同的 Key 搭配相同的 video_url 和 resolution，会以 200 OK 返回原来的任务，不会再次扣费。
相同的 Key 搭配不同的 video_url 或 resolution，返回 409 idempotency_conflict。
不带该请求头时，每个请求都会新建任务并扣费。

计费

价格 = 视频时长（按整秒向上取整）× 对应分辨率的费率。参见积分与价格。一段 12.4 秒的视频增强到 2K 需要 13 × 2 = 26 积分。

如果任务失败，积分会自动退还，任务状态变为 failed。

错误

状态码	错误码	触发条件
`400`	`invalid_request`	`video_url`、`resolution` 或 `Idempotency-Key` 缺失或无效
`401`	`unauthorized`	API 密钥缺失或无效
`403`	`paid_plan_required`	账号从未购买过积分或订阅
`402`	`insufficient_credits`	余额不足以处理该视频
`409`	`idempotency_conflict`	该 `Idempotency-Key` 已用于不同参数的请求
`413`	`file_too_large`	视频大于 500MB
`422`	`video_fetch_failed`	无法下载 `video_url`
`422`	`unsupported_video`	不是可读取的 MP4、MOV 或 WebM，或缺少时长信息
`422`	`video_too_long`	视频时长超过 600 秒
`422`	`video_not_found`	上传所得的 `video_url` 下没有文件（上传未完成）
`504`	`upstream_timeout`	下载 `video_url` 超过 4 分钟

错误格式参见错误。

创建画质增强任务

请求

请求头

请求体

视频要求

示例

响应

幂等性

计费

错误

On this page

创建画质增强任务

请求

请求头

请求体

视频要求

示例

响应

幂等性

计费

错误

On this page