> 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/credits.md).

# Credits

VIESUS Cloud uses a credit system. Credits are consumed per enhancement based on the features applied. Unused credits in a billing period do not carry forward unless specified by your subscription plan.

***

## Check remaining credits

```graphql
query {
  credits {
    periodStart
    periodEnd
    usedCreditsThisPeriod
    remainingCreditsThisPeriod
  }
}
```

***

## Image enhancement credits

When multiple features are active in a single enhancement, only the **highest-cost feature** is charged — credits do not add up.

| Feature             | Credits per image |
| ------------------- | ----------------- |
| Color Enhancement   | 1                 |
| Restoration         | 1                 |
| Background Handling | 4                 |
| AI Upscaling        | 4                 |

### Examples

| Features active                    | Charged                          |
| ---------------------------------- | -------------------------------- |
| Color Enhancement only             | 1 credit                         |
| Color Enhancement + Restoration    | 1 credit (both cost 1; max is 1) |
| Color Enhancement + AI Upscaling   | 4 credits (max of 1 and 4)       |
| Background Handling + AI Upscaling | 4 credits (max of 4 and 4)       |
| All features combined              | 4 credits                        |

***

## PDF enhancement credits

PDF credits are calculated from the analysis results. Run [PDF analysis](https://github.com/Viesus-AG/gitbook-sync/blob/published/viesus-docs/reference/cloud-api/pdf-enhancement/README.md#step-2--wait-for-analysis) first — the `metadata` field reports estimated cost before you commit to an enhancement.

The analysis reports three numbers:

* **Total** — total embedded images in the PDF
* **Enhancement** — images eligible for color enhancement
* **Resizing** — images eligible for AI upscaling

**Credit formulas:**

```powershell
Base cost     = Total ÷ 2 × 1
Resizing cost = Resizing × 3
Color cost    = Enhancement × 1

All features  = Base + Resizing + Color
No upscaling  = Base + Color
No color      = Base + Resizing
```

### Example calculation

PDF with 40 total images, 31 eligible for color, 9 eligible for resizing:

<table><thead><tr><th>Scenario</th><th width="321.7999267578125">Calculation</th><th>Credits</th></tr></thead><tbody><tr><td>All features</td><td>40÷2 + 31×1 + 9×3 = 20 + 31 + 27</td><td><strong>78</strong></td></tr><tr><td>No upscaling</td><td>20 + 31</td><td><strong>51</strong></td></tr><tr><td>No color enhancement</td><td>20 + 27</td><td><strong>47</strong></td></tr></tbody></table>

***

## AI upscaling limits

| Constraint                | Value                       |
| ------------------------- | --------------------------- |
| Maximum input dimension   | 3,000 px (width or height)  |
| Maximum enlargement ratio | 4×                          |
| Maximum output dimension  | 11,996 px (width or height) |

**PDF output resolution limits by subscription:**

| Subscription | Maximum target resolution |
| ------------ | ------------------------- |
| Free         | 300 DPI                   |
| Basic        | 600 DPI                   |
| Business     | 1,200 DPI                 |

***

## Upload retention

Uploads are stored for **30 days** by default, then automatically deleted. You are not charged for storage — this is a data management setting.

**Change default retention for new uploads:**

```graphql
mutation {
  updateFileRetention(days: 7) {
    uploadRetentionDays
  }
}
```

This applies to uploads made after the change. Existing uploads keep their original 30-day retention.

**Delete an upload immediately:**

```graphql
mutation {
  deleteUploads(ids: ["upload-id"]) {
    deletedUploadIds
  }
}
```

Multiple uploads can be deleted in one call by passing multiple IDs.

***

## Managing costs

**Review PDF credit estimate before enhancing** — the analysis phase is free. Check `metadata.totalCredits` before calling `createEnhancedImage`.

**Disable upscaling when not needed** — set `targetResolution` to match the actual embedded image resolution to avoid triggering resizing credits.

**One upload, multiple enhancements** — the same upload can be enhanced multiple times without re-upload costs. Use this to test different parameter combinations cheaply.

**Track usage by period** — use the `credits` query to monitor consumption and avoid surprises at billing time.


---

# 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/credits.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.