Uploading

Upload images and PDFs to VIESUS Cloud via URL or signed upload URL. Response fields, retention, and deletion.

Every enhancement starts with an upload. The upload creates a persistent file record that you reference by id in subsequent enhancement requests.

---

Which method to use

Your file is...	Method
At a reachable public URL	Upload from URL — simpler
On your server or local machine	Signed upload URL

---

Upload from a URL

The simplest method. VIESUS Cloud fetches the file directly from the URL you provide.

mutation {
  createUploadFromUrl(
    input: {
      url: "https://www.example.com/photo.jpg"
    }
  ) {
    id
    status
    filesize
    mimetype
    extension
    originalFilename
    filename
    width
    height
    url
    startedAt
    finishedAt
    duration
  }
}

Save the returned id — you need it to trigger enhancements.

curl example:

curl -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 status } }"
  }'

---

Upload with a signed URL

For files on your server, local machine, or user uploads that go directly from the browser to VIESUS Cloud storage. This is a three-step process.

1

Request a signed URL

mutation {
  createSignedUploadUrl(
    input: {
      filename: "photo.jpg"
      filesize: 2048000
      mimetype: "image/jpeg"
    }
  ) {
    uploadId
    uploadUrl
  }
}

filesize and mimetype must match the actual file. Incorrect values cause the upload to fail at the final step.

2

PUT the file to the signed URL

Use the uploadUrl from the previous step to PUT the file directly to storage:

Node.js:

const fs = require('fs');

const filePath = './photo.jpg';
const fileBuffer = fs.readFileSync(filePath);
const stats = fs.statSync(filePath);

await fetch(uploadUrl, {
  method: 'PUT',
  body: fileBuffer,
  headers: {
    'Content-Type': 'image/jpeg',
    'Content-Length': stats.size.toString(),
  },
});

Browser (file input):

async function putFile(uploadUrl, file) {
  await fetch(uploadUrl, {
    method: 'PUT',
    body: await file.arrayBuffer(),
    headers: {
      'Content-Type': file.type,
    },
  });
}

curl:

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

3

Complete the upload

Finalize using the uploadId from the first step:

mutation {
  completeSignedUpload(id: "uploadId") {
    id
    status
    filesize
    mimetype
    width
    height
    url
    startedAt
    finishedAt
    duration
  }
}

The returned id is the upload ID for all subsequent enhancement requests.

---

Upload response fields

Field	Description
id	Upload identifier — required for enhancement mutations
status	Upload state
filesize	File size in bytes
mimetype	Detected MIME type
extension	File extension
originalFilename	Filename as uploaded
filename	Storage filename
width / height	Image dimensions in pixels (0 for PDFs)
url	URL to access the original uploaded file
startedAt / finishedAt	Upload timestamps (ISO 8601)
duration	Upload processing time in milliseconds

---

Upload retention

Uploads are stored for 30 days by default, then automatically deleted. To change the default retention for new uploads:

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

This setting applies to uploads made after the change — existing uploads keep their original retention.

To delete an upload immediately:

mutation {
  deleteUploads(ids: ["upload-id-1", "upload-id-2"]) {
    deletedUploadIds
  }
}

---

Multiple enhancements from one upload

The same upload can be enhanced multiple times with different parameters. You do not need to re-upload the file:

mutation EnhanceA {
  createEnhancedImage(uploadId: "upload-id", input: { mode: ENHANCE }) {
    id status
  }
}

mutation EnhanceB {
  createEnhancedImage(uploadId: "upload-id", input: { mode: ENHANCE, upscalingFactor: X2 }) {
    id status
  }
}

This is useful for generating multiple output variants (e.g., with and without upscaling) without paying upload costs twice.