mirror of
https://github.com/upscayl/upscayl.git
synced 2026-02-19 11:55:37 -05:00
751 lines
23 KiB
YAML
751 lines
23 KiB
YAML
openapi: "3.0.2"
|
|
info:
|
|
title: Upscayl Cloud API
|
|
description: |
|
|
API for Upscayl Cloud - An AI-powered image upscaling service.
|
|
Use this API to upscale images, check processing status, and manage uploads.
|
|
version: 1.0.0
|
|
contact:
|
|
name: Upscayl Support
|
|
url: mailto:support@upscayl.org
|
|
servers:
|
|
- url: https://api.upscayl.org
|
|
description: Upscayl Server
|
|
|
|
security:
|
|
- ApiKeyAuth: []
|
|
components:
|
|
responses:
|
|
BadRequest:
|
|
description: Invalid request parameters
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
example:
|
|
error: BAD_REQUEST
|
|
message: "Invalid request parameters provided"
|
|
|
|
NotFound:
|
|
description: Requested resource not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
example:
|
|
error: NOT_FOUND
|
|
message: "Requested resource could not be found"
|
|
Unauthorized:
|
|
description: Authentication failed or API key missing
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
example:
|
|
error: UNAUTHORIZED
|
|
message: "Invalid or missing API key"
|
|
|
|
TooManyRequests:
|
|
description: Rate limit exceeded
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
example:
|
|
error: RATE_LIMIT_EXCEEDED
|
|
message: "Too many requests. Try again in 1 hour"
|
|
InternalError:
|
|
description: Internal server error occurred
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
example:
|
|
error: INTERNAL_SERVER_ERROR
|
|
message: "An unexpected error occurred"
|
|
securitySchemes:
|
|
ApiKeyAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: X-API-Key
|
|
schemas:
|
|
TaskStatus:
|
|
type: object
|
|
required:
|
|
- status
|
|
- data
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [success]
|
|
data:
|
|
type: object
|
|
properties:
|
|
batchMode:
|
|
type: boolean
|
|
description: Whether task is in batch mode
|
|
enhanceFace:
|
|
type: boolean
|
|
description: Whether face enhancement is enabled
|
|
error:
|
|
type: string
|
|
description: Error message if task failed
|
|
files:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/ProcessedFile"
|
|
model:
|
|
type: string
|
|
description: AI model used for processing
|
|
enum:
|
|
[
|
|
upscayl-standard-4x,
|
|
upscayl-lite-4x,
|
|
clear-boost-4x,
|
|
crystal-plus-4x,
|
|
digital-art-4x,
|
|
digital-art-plus-4x,
|
|
natural-max-4x,
|
|
natural-plus-4x,
|
|
nature-boost-4x,
|
|
pure-boost-4x,
|
|
quick-clear-4x,
|
|
texture-boost-4x,
|
|
]
|
|
progress:
|
|
type: string
|
|
description: Processing progress percentage
|
|
scale:
|
|
type: string
|
|
description: Upscale factor applied
|
|
status:
|
|
type: string
|
|
enum: [pending, processing, completed, failed]
|
|
saveImageAs:
|
|
type: string
|
|
enum: [png, jpg, webp]
|
|
# compression:
|
|
# type: number
|
|
# minimum: 0
|
|
# maximum: 100
|
|
creditsDeducted:
|
|
type: boolean
|
|
deductedCredits:
|
|
type: number
|
|
UploadedFile:
|
|
type: object
|
|
required:
|
|
- fileName
|
|
- fileType
|
|
- fileSize
|
|
properties:
|
|
fileName:
|
|
type: string
|
|
description: Unique file identifier
|
|
fileType:
|
|
type: string
|
|
description: MIME type of file
|
|
enum: [image/jpeg, image/png, image/webp]
|
|
fileSize:
|
|
type: integer
|
|
description: File size in bytes
|
|
minimum: 1
|
|
maximum: 104857600
|
|
originalFileName:
|
|
type: string
|
|
description: Original uploaded filename
|
|
createdAt:
|
|
type: integer
|
|
format: int64
|
|
description: Upload timestamp (Unix ms)
|
|
expiresAt:
|
|
type: integer
|
|
format: int64
|
|
description: Expiration timestamp (Unix ms)
|
|
ProcessingTask:
|
|
type: object
|
|
properties:
|
|
batchMode:
|
|
type: boolean
|
|
description: Whether task was processed in batch mode
|
|
enhanceFace:
|
|
type: boolean
|
|
description: Whether face enhancement was applied
|
|
error:
|
|
type: string
|
|
description: Error message if processing failed
|
|
files:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/ProcessedFile"
|
|
model:
|
|
type: string
|
|
description: AI model used for processing
|
|
enum:
|
|
[
|
|
upscayl-standard-4x,
|
|
upscayl-lite-4x,
|
|
clear-boost-4x,
|
|
crystal-plus-4x,
|
|
digital-art-4x,
|
|
digital-art-plus-4x,
|
|
natural-max-4x,
|
|
natural-plus-4x,
|
|
nature-boost-4x,
|
|
pure-boost-4x,
|
|
quick-clear-4x,
|
|
texture-boost-4x,
|
|
]
|
|
progress:
|
|
type: string
|
|
description: Processing progress percentage
|
|
scale:
|
|
type: string
|
|
description: Upscale factor applied
|
|
status:
|
|
type: string
|
|
enum: [pending, processing, completed, failed]
|
|
saveImageAs:
|
|
type: string
|
|
enum: [png, jpg, webp]
|
|
# compression:
|
|
# type: number
|
|
# minimum: 0
|
|
# maximum: 100
|
|
creditsDeducted:
|
|
type: boolean
|
|
|
|
ProcessedFile:
|
|
type: object
|
|
properties:
|
|
fileName:
|
|
type: string
|
|
fileType:
|
|
type: string
|
|
path:
|
|
type: string
|
|
createdAt:
|
|
type: integer
|
|
format: int64
|
|
expiresAt:
|
|
type: integer
|
|
format: int64
|
|
originalFileName:
|
|
type: string
|
|
fileSize:
|
|
type: integer
|
|
downloadLink:
|
|
type: string
|
|
format: uri
|
|
thumbnailLink:
|
|
type: string
|
|
format: uri
|
|
finalFileSize:
|
|
type: integer
|
|
processedFileName:
|
|
type: string
|
|
dimensions:
|
|
type: object
|
|
properties:
|
|
width:
|
|
type: integer
|
|
minimum: 1
|
|
height:
|
|
type: integer
|
|
minimum: 1
|
|
Error:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
message:
|
|
type: string
|
|
tags:
|
|
- name: Upload
|
|
description: File upload operations
|
|
- name: Tasks
|
|
description: Image processing task operations
|
|
- name: History
|
|
description: Historical data operations
|
|
|
|
paths:
|
|
/get-upload-url:
|
|
post:
|
|
tags:
|
|
- Upload
|
|
summary: Generate Pre-signed Upload URL
|
|
description: |
|
|
Generates a pre-signed URL for secure direct file upload to cloud storage.
|
|
The URL expires after a specified duration for security.
|
|
|
|
**Note**: File size is limited to 100MB per upload.
|
|
operationId: getUploadUrl
|
|
security:
|
|
- ApiKeyAuth: []
|
|
x-rateLimit:
|
|
requests: 100
|
|
period: 1 hour
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- originalFileName
|
|
- fileType
|
|
- fileSize
|
|
properties:
|
|
originalFileName:
|
|
type: string
|
|
description: Original name of the file to be uploaded
|
|
example: vacation-photo.jpeg
|
|
minLength: 1
|
|
maxLength: 255
|
|
fileType:
|
|
type: string
|
|
description: MIME type of the file
|
|
example: image/jpeg
|
|
enum:
|
|
- image/jpeg
|
|
- image/png
|
|
- image/webp
|
|
fileSize:
|
|
type: integer
|
|
description: File size in bytes (max 100MB)
|
|
example: 1048576
|
|
minimum: 1
|
|
maximum: 104857600
|
|
responses:
|
|
"200":
|
|
description: Pre-signed URL generated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- status
|
|
- data
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [success]
|
|
data:
|
|
type: object
|
|
required:
|
|
- uploadURL
|
|
- fileName
|
|
- expiresAt
|
|
properties:
|
|
uploadURL:
|
|
type: string
|
|
format: uri
|
|
description: Pre-signed URL for upload
|
|
example: https://storage.upscayl.com/upload/abc123
|
|
fileName:
|
|
type: string
|
|
description: Generated unique filename
|
|
example: f7d9a2b4-vacation-photo.jpeg
|
|
fileType:
|
|
type: string
|
|
description: MIME type of file
|
|
example: image/jpeg
|
|
fileSize:
|
|
type: integer
|
|
description: File size in bytes
|
|
example: 1048576
|
|
originalFileName:
|
|
type: string
|
|
description: Original filename
|
|
example: vacation-photo.jpeg
|
|
createdAt:
|
|
type: integer
|
|
format: int64
|
|
description: URL creation timestamp (Unix ms)
|
|
example: 1633024800000
|
|
expiresAt:
|
|
type: integer
|
|
format: int64
|
|
description: URL expiration timestamp (Unix ms)
|
|
example: 1633028400000
|
|
"400":
|
|
description: Invalid request parameters
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
examples:
|
|
InvalidFileType:
|
|
value:
|
|
error: INVALID_FILE_TYPE
|
|
message: "Unsupported file type. Allowed: JPEG, PNG, WEBP"
|
|
FileSizeTooLarge:
|
|
value:
|
|
error: FILE_SIZE_EXCEEDED
|
|
message: "File size exceeds maximum limit of 100MB"
|
|
MissingFields:
|
|
value:
|
|
error: MISSING_REQUIRED_FIELDS
|
|
message: "Required fields missing: originalFileName"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"429":
|
|
$ref: "#/components/responses/TooManyRequests"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/get-upscayl-history:
|
|
post:
|
|
tags:
|
|
- History
|
|
summary: Get Image Processing History
|
|
description: |
|
|
Retrieves paginated history of image processing tasks.
|
|
Results can be filtered by status and time range.
|
|
operationId: getUpscaylHistory
|
|
security:
|
|
- ApiKeyAuth: []
|
|
x-rateLimit:
|
|
requests: 100
|
|
period: 1 hour
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
timestampOffset:
|
|
type: integer
|
|
format: int64
|
|
description: Unix timestamp (ms) to start fetching records from
|
|
example: 1633024800000
|
|
batch:
|
|
type: boolean
|
|
description: Filter by batch processing status
|
|
example: true
|
|
failed:
|
|
type: boolean
|
|
description: Filter by failed status
|
|
example: false
|
|
limit:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 100
|
|
default: 20
|
|
description: Number of records to return per page
|
|
example: 10
|
|
processed:
|
|
type: string
|
|
enum: [pending, processing, completed, failed]
|
|
description: Filter by processing status
|
|
example: processing
|
|
responses:
|
|
"200":
|
|
description: Successfully retrieved history
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- status
|
|
- data
|
|
- pagination
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [success]
|
|
pagination:
|
|
type: object
|
|
properties:
|
|
total:
|
|
type: integer
|
|
description: Total number of records
|
|
hasMore:
|
|
type: boolean
|
|
description: Whether more records exist
|
|
nextOffset:
|
|
type: integer
|
|
format: int64
|
|
description: Timestamp offset for next page
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/ProcessingTask"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"429":
|
|
$ref: "#/components/responses/TooManyRequests"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/get-task-status:
|
|
post:
|
|
tags:
|
|
- Tasks
|
|
summary: Check Task Status
|
|
description: |
|
|
Get current status and progress of an upscaling task.
|
|
Returns detailed information about the task including processed files and progress.
|
|
operationId: getTaskStatus
|
|
security:
|
|
- ApiKeyAuth: []
|
|
x-rateLimit:
|
|
requests: 100
|
|
period: 1 hour
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- taskId
|
|
properties:
|
|
taskId:
|
|
type: string
|
|
format: uuid
|
|
description: Task ID returned by start-task endpoint. See [Start Image Upscaling Task](/start-a-new-task).
|
|
example: 30a89e69-c702-4247-9905-f0a53dfa45ab
|
|
responses:
|
|
"200":
|
|
description: Task status retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TaskStatus"
|
|
example:
|
|
status: success
|
|
data:
|
|
batchMode: false
|
|
enhanceFace: true
|
|
model: digital-art-4x
|
|
progress: "75"
|
|
scale: "4"
|
|
status: processing
|
|
files: []
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"429":
|
|
$ref: "#/components/responses/TooManyRequests"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/start-task:
|
|
post:
|
|
tags:
|
|
- Tasks
|
|
summary: Start Task
|
|
description: |
|
|
Initiates a new image upscaling task with specified parameters.
|
|
Supports both direct file upload and processing of previously uploaded files.
|
|
operationId: startTask
|
|
security:
|
|
- ApiKeyAuth: []
|
|
x-rateLimit:
|
|
requests: 50
|
|
period: 1 hour
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
files:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/UploadedFile"
|
|
description: Array of previously uploaded files to process
|
|
file:
|
|
type: string
|
|
format: binary
|
|
description: Single file for direct upload (mutually exclusive with files array)
|
|
enhanceFace:
|
|
type: boolean
|
|
description: Enable face enhancement
|
|
default: false
|
|
model:
|
|
type: string
|
|
description: AI model for upscaling
|
|
enum:
|
|
[
|
|
upscayl-standard-4x,
|
|
upscayl-lite-4x,
|
|
clear-boost-4x,
|
|
crystal-plus-4x,
|
|
digital-art-4x,
|
|
digital-art-plus-4x,
|
|
natural-max-4x,
|
|
natural-plus-4x,
|
|
nature-boost-4x,
|
|
pure-boost-4x,
|
|
quick-clear-4x,
|
|
texture-boost-4x,
|
|
]
|
|
example: digital-art
|
|
scale:
|
|
type: string
|
|
description: Upscaling factor
|
|
enum: ["2", "4", "8"]
|
|
example: "4"
|
|
# TODO: compression:
|
|
# type: number
|
|
# description: Output image compression (0-100)
|
|
# minimum: 0
|
|
# maximum: 100
|
|
# default: 0
|
|
saveImageAs:
|
|
type: string
|
|
enum: [png, jpg, webp]
|
|
description: Output image format
|
|
default: jpg
|
|
responses:
|
|
"200":
|
|
description: Task started successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- status
|
|
- data
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [success]
|
|
data:
|
|
type: object
|
|
required:
|
|
- taskId
|
|
- message
|
|
properties:
|
|
taskId:
|
|
type: string
|
|
format: uuid
|
|
example: 30a89e69-c702-4247-9905-f0a53dfa45ab
|
|
message:
|
|
type: string
|
|
example: Task request sent successfully
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"402":
|
|
description: Insufficient credits
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
example:
|
|
error: INSUFFICIENT_CREDITS
|
|
message: Not enough credits to process request
|
|
"429":
|
|
$ref: "#/components/responses/TooManyRequests"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
/complete-multipart-upload:
|
|
post:
|
|
tags:
|
|
- Upload
|
|
summary: Complete Multipart Upload
|
|
description: |
|
|
Completes a multipart upload by combining previously uploaded parts in S3.
|
|
Must be called after all parts have been uploaded using pre-signed URLs.
|
|
operationId: completeMultipartUpload
|
|
security:
|
|
- ApiKeyAuth: []
|
|
x-rateLimit:
|
|
requests: 50
|
|
period: 1 hour
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- data
|
|
properties:
|
|
data:
|
|
type: object
|
|
required:
|
|
- uploadId
|
|
- key
|
|
- parts
|
|
properties:
|
|
uploadId:
|
|
type: string
|
|
description: S3 upload ID
|
|
example: "abc123def456"
|
|
key:
|
|
type: string
|
|
description: S3 object key
|
|
example: "uploads/image.jpg"
|
|
parts:
|
|
type: array
|
|
description: List of uploaded parts
|
|
minItems: 1
|
|
items:
|
|
type: object
|
|
required:
|
|
- PartNumber
|
|
- ETag
|
|
properties:
|
|
PartNumber:
|
|
type: integer
|
|
minimum: 1
|
|
description: Part number
|
|
example: 1
|
|
ETag:
|
|
type: string
|
|
description: ETag from part upload
|
|
example: "a1b2c3d4"
|
|
responses:
|
|
"200":
|
|
description: Multipart upload completed successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- status
|
|
- data
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [success]
|
|
data:
|
|
type: object
|
|
required:
|
|
- status
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [success]
|
|
"400":
|
|
description: Missing or invalid parameters
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
example:
|
|
error: BAD_REQUEST
|
|
message: "Bad Request: Missing required parameters"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"500":
|
|
description: S3 or internal error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
example:
|
|
error: INTERNAL_SERVER_ERROR
|
|
message: "Error completing multipart upload"
|