> For the complete documentation index, see [llms.txt](https://docs.viesus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.viesus.com/reference/cloud-api/overview.md).

# Overview

VIESUS Cloud is a fully managed API that gives you access to the complete VIESUS enhancement engine without installing or operating any infrastructure. Upload images or PDFs, trigger enhancements, and retrieve results — pay only for what you process.

***

## API endpoint

All requests go to a single GraphQL endpoint:

```powershell
https://api.viesus.cloud/graphql
```

Requests are standard HTTP POST with a JSON body. Any GraphQL client library or plain `fetch`/`curl` works.

| Language | Recommended library        |
| -------- | -------------------------- |
| Node.js  | `graphql-request`          |
| Python   | `gql`                      |
| PHP      | `webonyx/graphql-php`      |
| Go       | `hasura/go-graphql-client` |

### GraphQL Playground

Explore the full schema and run queries interactively: <https://api.viesus.cloud/graphiql>

Add your `x-api-key` header and run any mutation or query directly from the browser. The schema browser shows all available enum values and input types.

***

## How it works

Every integration follows five steps:

```powershell
1. Authenticate  →  x-api-key header on every request
2. Upload        →  from URL or via signed upload URL
3. Enhance       →  createEnhancedImage mutation
4. Poll / webhook →  check status or receive push notification
5. Retrieve      →  download from fullUrl
```

The same upload can be enhanced multiple times with different parameters — useful for A/B testing configurations or generating multiple output variants.

***

## Supported file types

<table><thead><tr><th width="102.5999755859375">Format</th><th width="163.60009765625">MIME type</th><th>Notes</th></tr></thead><tbody><tr><td>JPEG</td><td><code>image/jpeg</code></td><td></td></tr><tr><td>PNG</td><td><code>image/png</code></td><td></td></tr><tr><td>TIFF</td><td><code>image/tiff</code></td><td></td></tr><tr><td>HEIC</td><td><code>image/heic</code></td><td>Currently converted to JPEG after processing — this will change in a future version</td></tr><tr><td>WebP</td><td><code>image/webp</code></td><td>Currently converted to JPEG after processing — this will change in a future version</td></tr><tr><td>PDF</td><td><code>application/pdf</code></td><td>Requires analysis phase before enhancement</td></tr></tbody></table>

**File size limits:**

| Type      | Minimum | Maximum  |
| --------- | ------- | -------- |
| Images    | 20 KB   | 50 MB    |
| PDF files | 20 KB   | 1,000 MB |

***

## Use cases

<table><thead><tr><th width="310">Scenario</th><th>Approach</th></tr></thead><tbody><tr><td>SaaS product — enhance on upload</td><td>Signed upload URL → webhook on completion</td></tr><tr><td>Batch from existing CDN</td><td>Upload from URL in a loop → poll or webhook</td></tr><tr><td>PDF print workflow</td><td>Upload PDF → wait for analysis → enhance</td></tr><tr><td>A/B test enhancement settings</td><td>One upload → multiple <code>createEnhancedImage</code> calls</td></tr><tr><td>One-off manual enhancement</td><td>Dashboard UI (no API required)</td></tr></tbody></table>

***

## Quick example

```bash
# 1. Upload from URL
UPLOAD_ID=$(curl -s -X POST https://api.viesus.cloud/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR-API-KEY" \
  -d '{"query":"mutation { createUploadFromUrl(input: { url: \"https://example.com/photo.jpg\" }) { id } }"}' \
  | jq -r '.data.createUploadFromUrl.id')

# 2. Enhance
ENHANCEMENT_ID=$(curl -s -X POST https://api.viesus.cloud/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR-API-KEY" \
  -d "{\"query\":\"mutation { createEnhancedImage(uploadId: \\\"$UPLOAD_ID\\\", input: { mode: ENHANCE }) { id status } }\"}" \
  | jq -r '.data.createEnhancedImage.id')

# 3. Check status
curl -s -X POST https://api.viesus.cloud/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR-API-KEY" \
  -d "{\"query\":\"query { enhancedImage(id: \\\"$ENHANCEMENT_ID\\\") { status fullUrl } }\"}"
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.viesus.com/reference/cloud-api/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.