> ## Documentation Index
> Fetch the complete documentation index at: https://docs.legnext.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Topaz Upscale Image
> Upscale images to ultra-high resolutions up to 12K
Supports direct image URLs or images from previous Midjourney tasks.
## Input Methods
Choose one of the following input methods:
### Option 1: Direct Image URL
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | -------------------------------------------------------------------------------- |
| `image_url` | string | Yes | Publicly accessible image URL (HTTP/HTTPS). Supports JPEG, PNG, TIFF. Max: 100MB |
### Option 2: Midjourney Task
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | -------------------------------- |
| `jobId` | string | Yes | ID from previous Midjourney task |
| `imageNo` | integer | Yes | Image index from grid (0-3) |
### Common Parameters
All enhancement requests support the following parameters:
| Parameter | Type | Default | Description |
| ------------------------ | ------ | ----------- | ------------------------------------------------------------------------------------- |
| `target_resolution` | string | `2K` | Output resolution: `HD`, `FHD`, `2K`, `4K`, `6K`, `8K`, `12K` |
| `content_type` | string | `standard` | Enhancement model: `standard`, `photo`, `illustration`, `text`, `low_res` |
| `aspect_ratio` | string | `keep` | Aspect ratio: `keep`, `1:1`, `16:9`, `9:16`, `4:5`, `5:4`, `3:2`, `2:3`, `4:3`, `3:4` |
| `crop_mode` | string | `letterbox` | Crop handling: `letterbox`, `crop`, `stretch` |
| `output_format` | string | `jpeg` | Output format: `jpeg`, `jpg`, `png`, `tiff`, `tif` |
| `face_enhancement_level` | string | `moderate` | Face enhancement: `off`, `none`, `subtle`, `moderate`, `strong` |
| `callback` | string | - | Webhook URL for completion notifications |
## Resolution Options
| Resolution | Long Edge | Credits | Cost | Recommended For |
| ---------- | --------- | ------- | ------ | --------------------------- |
| HD/FHD | 1920px | 120 | \$0.12 | Web, social media |
| 2K | 2560px | 120 | \$0.12 | Web, social media (default) |
| 4K | 3840px | 160 | \$0.16 | Digital displays |
| 6K | 6144px | 200 | \$0.20 | Professional printing |
| 8K | 7680px | 300 | \$0.30 | Large format prints |
| 12K | 12288px | 540 | \$0.54 | Billboards, posters |
Higher resolutions consume more credits and take longer to process. Choose the minimum resolution that meets your requirements.
## Content Type Models
| Type | Best For |
| -------------- | ---------------------------------------- |
| `standard` | General purpose, mixed content (default) |
| `photo` | Photographs, realistic images |
| `illustration` | Digital art, CGI, drawings |
| `text` | Documents, screenshots with text |
| `low_res` | Very low quality source images |
## Face Enhancement
| Level | Effect |
| -------------- | -------------------------------------------- |
| `off` / `none` | Disabled (no faces in image) |
| `subtle` | Gentle enhancement for natural portraits |
| `moderate` | Balanced enhancement (default) |
| `strong` | Aggressive enhancement for low-quality faces |
## Examples
### Using Image URL
```bash cURL theme={null}
curl -X POST "https://api.legnext.ai/api/v1/enhance-upscale" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://example.com/photo.jpg",
"target_resolution": "4K",
"content_type": "photo"
}'
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.legnext.ai/api/v1/enhance-upscale",
headers={"x-api-key": "YOUR_API_KEY"},
json={
"image_url": "https://example.com/photo.jpg",
"target_resolution": "4K",
"content_type": "photo"
}
)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.legnext.ai/api/v1/enhance-upscale', {
method: 'POST',
headers: {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
image_url: 'https://example.com/photo.jpg',
target_resolution: '4K',
content_type: 'photo'
})
});
console.log(await response.json());
```
### Using Midjourney Task
```bash cURL theme={null}
curl -X POST "https://api.legnext.ai/api/v1/enhance-upscale" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jobId": "1868588555208310784",
"imageNo": 0,
"target_resolution": "8K",
"content_type": "illustration"
}'
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.legnext.ai/api/v1/enhance-upscale",
headers={"x-api-key": "YOUR_API_KEY"},
json={
"jobId": "1868588555208310784",
"imageNo": 0,
"target_resolution": "8K",
"content_type": "illustration"
}
)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.legnext.ai/api/v1/enhance-upscale', {
method: 'POST',
headers: {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
jobId: '1868588555208310784',
imageNo: 0,
target_resolution: '8K',
content_type: 'illustration'
})
});
console.log(await response.json());
```
## Response
### Success Response
Returns a task object with the following structure:
```json theme={null}
{
"job_id": "f3efd852-18ad-483d-87f2-0685a60df014",
"model": "midjourney",
"task_type": "enhance_upscale",
"status": "pending",
"config": {
"service_mode": "public",
"webhook_config": {
"endpoint": "",
"secret": ""
}
},
"input": null,
"output": {
"image_url": "",
"image_urls": null,
"seed": ""
},
"meta": {
"created_at": "2025-12-17T03:22:29+08:00",
"started_at": "0001-01-01T00:00:00Z",
"ended_at": "0001-01-01T00:00:00Z",
"usage": {
"type": "point",
"frozen": 300,
"consume": 0
}
},
"detail": null,
"logs": [],
"error": {
"code": 0,
"raw_message": "",
"message": "",
"detail": null
}
}
```
### Response Fields
| Field | Type | Description |
| -------------------------------- | ----------- | ----------------------------------------------------------------------------- |
| `job_id` | string | Unique task identifier (UUID) |
| `model` | string | Model used: `midjourney` |
| `task_type` | string | Task type: `enhance_upscale` |
| `status` | string | Current status: `pending`, `processing`, `completed`, `failed` |
| `config` | object | Service configuration |
| `config.service_mode` | string | Service mode: `public` |
| `config.webhook_config` | object | Webhook configuration |
| `config.webhook_config.endpoint` | string | Webhook endpoint URL (empty if not set) |
| `config.webhook_config.secret` | string | Webhook secret (empty if not set) |
| `input` | object/null | Input parameters (null for this endpoint) |
| `output` | object | Task output (empty until completed) |
| `output.image_url` | string | Primary enhanced image URL (available when `status` is `completed`) |
| `output.image_urls` | array/null | Array of enhanced image URLs (null until completed) |
| `output.seed` | string | Generation seed (empty for enhancement tasks) |
| `meta` | object | Task metadata |
| `meta.created_at` | string | Task creation timestamp (ISO 8601) |
| `meta.started_at` | string | Task start timestamp (ISO 8601, `0001-01-01T00:00:00Z` if not started) |
| `meta.ended_at` | string | Task completion timestamp (ISO 8601, `0001-01-01T00:00:00Z` if not completed) |
| `meta.usage` | object | Credit usage information |
| `meta.usage.type` | string | Usage type: `point` |
| `meta.usage.frozen` | integer | Credits frozen/reserved for this task |
| `meta.usage.consume` | integer | Credits actually consumed (0 if task failed) |
| `detail` | object/null | Additional task details (null if none) |
| `logs` | array | Processing logs (empty array) |
| `error` | object | Error information |
| `error.code` | integer | Error code (0 if successful) |
| `error.raw_message` | string | Raw error message from service (empty if successful) |
| `error.message` | string | Human-readable error message (empty if successful) |
| `error.detail` | object/null | Additional error details (null if none) |
Use the `job_id` to check task status via the [Get Task Status](/api-reference/task-management/get-task) endpoint.
## OpenAPI
````yaml POST /v1/enhance-upscale
openapi: 3.0.3
info:
title: Legnext AI API
description: >
Comprehensive API for professional image and video generation and
manipulation using Midjourney AI models.
## Authentication
All API requests require an API key passed in the `x-api-key` header.
## Base URL
`https://api.legnext.ai/api`
## Rate Limiting
API requests are rate limited based on your subscription plan.
## Webhook Support
Most endpoints support optional callbacks. When a callback URL is provided,
the API will POST the completed job result to that URL.
version: 1.0.0
contact:
name: Legnext Support
email: support@legnext.ai
url: https://legnext.ai
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.legnext.ai/api
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Image Generation
description: Text to image, image editing, and manipulation endpoints
- name: Video Generation
description: Video creation and enhancement endpoints
- name: Image Enhancement
description: AI-powered image upscaling and enhancement using Topaz Labs
- name: Task Management
description: Job status tracking and retrieval
- name: Account
description: Account information and active tasks management
paths:
/v1/enhance-upscale:
post:
tags:
- Image Enhancement
summary: Enhance and Upscale Image
description: >-
Upscale images to ultra-high resolutions (up to 12K) using Topaz Labs AI
with content-aware enhancement.
operationId: enhanceUpscaleImage
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EnhanceUpscaleRequest'
responses:
'200':
description: Enhancement task created successfully
content:
application/json:
schema:
$ref: 6d781e11-1d35-4b14-b58a-515c92e0dd0e
'400':
description: Bad Request - Invalid request parameters or malformed request body
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Invalid request, image_url must start with http:// or https://
raw_message: image_url must start with http:// or https://
detail: null
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 401
message: Failed to verify api key
raw_message: ''
detail: null
'402':
description: >-
Payment Required - Insufficient credits in user account or provider
account issue
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 402
message: insufficient quota
raw_message: insufficient quota
detail: null
'403':
description: Forbidden - Sensitive content detected or permission denied
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 403
message: Forbidden - Sensitive content detected
raw_message: Forbidden - Sensitive content detected
detail: null
'413':
description: Payload Too Large - File size exceeds maximum limit (100MB)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 413
message: File size exceeds maximum limit (100MB)
raw_message: 'file too large: exceeded 100MB'
detail: null
'422':
description: Unprocessable Entity - Invalid parameter values or validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 422
message: Invalid parameter values
raw_message: target_resolution must be one of HD, FHD, 2K, 4K, 6K, 8K, 12K
detail: null
'429':
description: Too Many Requests - Rate limit exceeded (automatically retried)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 429
message: rate limit exceeded, please retry later
raw_message: rate limit exceeded, please retry later
detail: null
'500':
description: Internal Server Error - Server-side error (automatically retried)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 500
message: Internal server error
raw_message: Internal server error
detail: null
security:
- ApiKeyAuth: []
components:
schemas:
EnhanceUpscaleRequest:
type: object
properties:
image_url:
type: string
format: uri
pattern: ^https?://
maxLength: 2048
description: >-
Direct image URL to enhance. Must be publicly accessible. Supports
JPEG, PNG, TIFF formats. Maximum file size: 100MB.
example: https://example.com/photo.jpg
jobId:
type: string
description: >-
Task ID from a previous Midjourney generation task. Use this to
enhance images from prior generations.
example: '1868588555208310784'
imageNo:
type: integer
minimum: 0
maximum: 3
description: >-
Image index from the Midjourney grid (0-3). Required when using
jobId.
example: 0
target_resolution:
type: string
enum:
- HD
- FHD
- 2K
- 4K
- 6K
- 8K
- 12K
default: 2K
description: Target output resolution. Higher resolutions cost more credits.
example: 4K
content_type:
type: string
enum:
- standard
- photo
- illustration
- text
- low_res
default: standard
description: Content-aware enhancement model selection.
example: photo
aspect_ratio:
type: string
enum:
- keep
- '1:1'
- '16:9'
- '9:16'
- '4:5'
- '5:4'
- '3:2'
- '2:3'
- '4:3'
- '3:4'
default: keep
description: Output aspect ratio. Use 'keep' to maintain original proportions.
example: keep
crop_mode:
type: string
enum:
- letterbox
- crop
- stretch
default: letterbox
description: How to handle aspect ratio changes when aspect_ratio is not 'keep'.
example: letterbox
output_format:
type: string
enum:
- jpeg
- jpg
- png
- tiff
- tif
default: jpeg
description: Output image format.
example: jpeg
face_enhancement_level:
type: string
enum:
- 'off'
- none
- subtle
- moderate
- strong
default: moderate
description: AI-powered face enhancement strength.
example: moderate
callback:
type: string
format: uri
description: Webhook URL for task completion notifications.
example: https://your-domain.com/webhook
anyOf:
- required:
- image_url
- required:
- jobId
- imageNo
Error:
type: object
properties:
code:
type: integer
description: Error code
example: 400
message:
type: string
description: Human-readable error message
example: Invalid request parameters
raw_message:
type: string
description: Raw error message from service
example: image_url must start with http:// or https://
detail:
type: object
nullable: true
description: Additional error details
example: null
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: API key for authentication
````