VezAPI Image Upscaler API 接入文档

使用 VezAPI 密钥接入 VezAPI Image Upscaler。下列操作共用同一个账号余额和鉴权方式。

图片放大在提交前按最高档每张 12 积分预留，最终按实际消耗扣分，未使用的预留会释放。

服务地址： https://api.vezapi.com
请求头使用 Authorization: Bearer YOUR_VEZAPI_KEY。每次提交使用唯一的 Idempotency-Key，查询同一笔提交时才复用。

VezAPI - 图片放大

POST/api/v1/jobs/createTask

模型标识： kie/image-upscale

参数	类型	说明与限制
`model` 必填	`string`	用于处理任务的模型名称。必填字段。 - 该接口必须使用 `kie/image-upscale` 模型可选值：`"kie/image-upscale"` 默认：`"kie/image-upscale"`
`callBackUrl` 可选	`string`	接收处理任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务处理完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含处理后内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态 - 回调可能投递不止一次，请按 `taskId` 去重 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法
`input` 必填	`object`	放大任务的输入参数
`input.image_url` 必填	`string`	待放大的图片地址。必填。 - 必须是公网可直接下载的 HTTP(S) URL - 最大文件大小：20 MB - 支持格式：JPG、PNG、WEBP、HEIC、BMP、GIF（只取第一帧） - 请使用上传后的文件 URL，而不是文件内容本身
`input.upscale_factor` 可选	`string`	宽、高各自乘的放大倍率，保持比例。可选。取值：`"1"` / `"2"` / `"4"` / `"8"`（传数字也可以），默认 `"2"`。 - `1`：同尺寸画质增强（去噪、锐化、文字保真），不改变尺寸 - `2` / `4` / `8`：输出宽高 = 输入 × 倍率 - 输出不得超过 67 MP（约 8192×8192）且单边 ≤ 16,384 像素，否则返回 422 且不扣费 - 计费档位（2K / 4K / 8K）按输出总像素确定可选值：`"1", "2", "4", "8"` 默认：`"2"`

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "kie/image-upscale",
  "input": {
    "image_url": "https://example.com/input.png"
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：`200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505`
`msg` 可选	`string`	Response message, error description upon failure
`data` 必填	`object`
`data.taskId` 必填	`string`	The task ID can be used with the "Get Task Details" endpoint to query the task status.

HTTP 500

Server error.

参数	类型	说明与限制
`code` 必填	`integer`	Response status code - 200: Success - Request has been processed successfully - 401: Unauthorized - Authentication credentials are missing or invalid - 402: Insufficient Credits - Account does not have enough credits to perform the operation - 404: Not Found - The requested resource or endpoint does not exist - 408: Timeout - No result has been returned for over 10 minutes. - 422: Validation Error - The request parameters failed validation checks - 429: Rate Limited - Request limit has been exceeded for this resource - 455: Service Unavailable - System is currently undergoing maintenance - 500: Server Error - An unexpected error occurred while processing the request - 501: Generation Failed - Content generation task failed - 505: Feature Disabled - The requested feature is currently disabled
`msg` 必填	`string`	Response message, error description when failed
`data` 必填	`object`

任务状态与回调

异步任务请保存返回的 taskId。调用 GET /api/v1/jobs/recordInfo?taskId=... 查询，或在创建时设置 callBackUrl。只有任务所属账号可以查询任务或基于任务创建派生资源。

超时可能表示请求已经受理。请在控制台查看原请求，不要自动新建任务。回调可能重试并重复到达，请使用 X-VezAPI-Event-Id 去重。

文件、日志与计费

生成媒体通常随上游保留 14 天，上传文件在 24 小时后失效。请在过期前保存所需文件。VezAPI 仅流式转发已登记资源，不提供永久作品库。请求日志保留两个自然月。

调用前预留积分，最终按实际优惠扣分 1:1 结算。用量不明时暂停新付费请求。若保护其他任务预留后余额不足以结算，会保留待结算记录，补足余额后再扣费；模型用量不会将钱包扣成负数。按时长计价的输入文件由服务端读取时长，读取失败时不提交模型任务。