Image Upscaler

Image Upscaler enhances one source image and returns a hosted 2K, 4K, or 8K result. It uses the standard asynchronous image task API, including polling, callbacks, credit refunds on failure, and durable platform-hosted output URLs.

Model

Model	Input	Output
`image-upscaler`	One public image URL	One enhanced image URL

Pricing

Every run costs 4 credits ($0.02). Target resolution and output format do not change the price. Existing account-specific pricing multipliers still apply.

Create a Task

curl -X POST https://api.aivideoapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "image-upscaler",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "image_urls": ["https://example.com/source-image.jpg"],
      "target_resolution": "4k",
      "output_format": "jpeg"
    }
  }'

Request Body

Field	Type	Required	Description
`model`	string	Yes	Must be `image-upscaler`
`input`	object	Yes	Upscaling parameters
`callback_url`	string	No	HTTP(S) URL notified when the task completes or fails

Input Parameters

Field	Type	Required	Description
`image_urls`	string[]	Yes	Exactly one public HTTP(S) source image URL
`target_resolution`	string	No	`2k`, `4k` (default), or `8k`
`output_format`	string	No	`jpeg` (default), `png`, or `webp`

The upstream-only enable_base64_output and enable_sync_mode fields are not supported. Results are always returned as URLs through the asynchronous task flow.

Create Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "397ce9f2-c04e-4244-ac33-3af19a7cc297"
  }
}

The 4-credit base price is pre-charged when the task is accepted. A failed task is refunded automatically.

Query a Task

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

Task status moves from pending to processing, then to completed or failed.

Completed

{
  "id": "397ce9f2-c04e-4244-ac33-3af19a7cc297",
  "status": "completed",
  "model": "image-upscaler",
  "created_at": 1785900000,
  "completed_at": 1785900015,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/images/2026/08/05/upscaled.webp"
    ]
  }
}

Failed

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "image-upscaler",
  "created_at": 1785900000,
  "error": {
    "code": "upstream_error",
    "message": "Image upscaling failed"
  }
}

Callback

Pass callback_url when creating the task. The platform sends a POST request after the result is copied to platform storage or after the task fails. The callback body matches the task query response.

Header	Description
`Content-Type`	`application/json`
`X-Event`	`task.completed` or `task.failed`
`X-Task-Id`	Platform task ID
`X-Timestamp`	Unix timestamp in seconds

Non-2xx responses and timeouts are retried up to three total attempts: immediately, after 3 minutes, and after 10 minutes. You can always fall back to GET /v1/tasks/{taskId}.

Error Codes

When a request fails, the API returns a JSON error response:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

Error Reference

HTTP Status	Code	Type	Description
400	`invalid_request`	invalid_request_error	Missing or invalid parameters
401	`invalid_api_key`	authentication_error	API key is invalid, disabled, or deleted
402	`insufficient_credits`	billing_error	Credit balance too low, please top up
403	`ip_not_allowed`	permission_error	Request IP not in the key's allowlist
404	`model_not_found`	invalid_request_error	Model does not exist or is inactive
404	`task_not_found`	invalid_request_error	Task ID does not exist
429	`rate_limit_exceeded`	rate_limit_error	Too many requests, please slow down
429	`spend_limit_exceeded`	billing_error	Key spend limit reached (hourly/daily/total)
500	`internal_error`	api_error	Unexpected server error
503	`upstream_error`	upstream_error	Upstream AI provider returned an error

Common Scenarios

invalid_request (400)

Returned when required fields are missing or invalid.

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

Your balance is too low. Check your balance with GET /v1/credits and top up in Dashboard > Billing.

invalid_api_key (401)

Possible causes:

The key does not start with sk-
The key has been disabled or deleted
The user account has been banned

upstream_error (503)

The upstream AI provider returned an error. This may happen when:

The input contains sensitive or prohibited content
The provider is temporarily unavailable
The request parameters are not supported by the provider

Credits are automatically refunded when a task fails due to upstream errors.