Enhance Images

Trigger image enhancements with createEnhancedImage. Parameters, status, AI upscaling limits, and polling vs webhooks.

Once an image is uploaded, trigger enhancement with the createEnhancedImage mutation. Processing takes 2–180 seconds depending on features and server load.

---

Create an enhancement

mutation {
  createEnhancedImage(
    uploadId: "your-upload-id"
    input: {
      mode: ENHANCE
      noiseReductionProfilingMode: AUTO
      noiseReductionProfilingStrength: 0.5
      artifactsDetectionRemoval: AUTO_AI
      enhanceFaceDetails: ENHANCE
      upscalingFactor: X2
    }
  ) {
    id
    status
    fullUrl
    filename
    viesusDuration
  }
}

Save the returned id — you need it to check status or retrieve the result later.

---

Input parameters

Parameter	Type	Description
mode	EnhancedImageEnhancementMode	Overall enhancement mode
preset	EnhancedImageParametersPreset	Pre-configured enhancement profile
noiseReductionProfilingMode	EnhancedImageParametersNoiseReductionProfilingMode	Noise reduction mode
noiseReductionProfilingStrength	Decimal	Noise reduction strength (0.0–1.0)
noiseReductionProfilingMonochromeStrength	Decimal	Monochrome noise reduction (0.0–1.0)
artifactsDetectionRemoval	EnhancedImageParametersArtifactsDetectionRemoval	JPEG artifact removal mode
enhanceFaceDetails	EnhancedImageParametersEnhanceFaceDetails	Face detail enhancement
redEyeCorrectionsMode	EnhancedImageParametersRedEyeCorrectionsMode	Red-eye correction mode
redEyeCorrectionsStrength	Decimal	Red-eye correction strength (0.0–1.0)
redEyeCorrectionsEyeStrength	Decimal	Eye correction strength (0.0–1.0)
noiseAdditionProfilingStrength	Decimal	Grain addition strength (0.0–1.0)
upscalingFactor	EnhancedImageParametersUpscalingFactor	AI upscaling factor (X2, X4, etc.)
upscalingCustomWidth	Int	Target output width in pixels
upscalingCustomDPI	Int	Target output DPI
backgroundRemovalMode	EnhancedImageParametersPortraitBackgroundMode	Background removal/replacement
backgroundRemovalBlur	Decimal	Background blur strength (0.0–1.0)
backgroundRemovalReplaceImageUrl	String	URL of a replacement background image
customColorConfig	CustomColorConfigInput	Manual color adjustments

For all enum values, open the schema browser at https://api.viesus.cloud/graphiql.

---

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)

AI upscaling costs 4 credits per image. See Credits.

---

Check enhancement status

query {
  enhancedImage(id: "enhancement-id") {
    id
    status
    fullUrl
    filename
    viesusDuration
    errorCode
  }
}

Status	Meaning
QUEUED	Waiting for a processing slot
FINISHED	Complete — fullUrl is ready to download
ERROR	Failed — inspect errorCode

When status is FINISHED, the enhanced image is available at fullUrl. The URL is valid for the duration of the upload's retention period.

---

All enhancements for an upload

Multiple enhancements can share a single upload (different parameters, different output variants):

query {
  upload(id: "upload-id") {
    id
    status
    EnhancedImages {
      id
      status
      fullUrl
      filename
      viesusDuration
      errorCode
    }
  }
}

---

Polling vs webhooks

Polling is straightforward but wastes requests when processing is slow:

async function waitForEnhancement(client, id, intervalMs = 3000) {
  while (true) {
    const { enhancedImage } = await client.request(STATUS_QUERY, { id });
    if (enhancedImage.status === 'FINISHED') return enhancedImage.fullUrl;
    if (enhancedImage.status === 'ERROR') throw new Error(`Enhancement failed: ${enhancedImage.errorCode}`);
    await new Promise(r => setTimeout(r, intervalMs));
  }
}

Webhooks are recommended for production — your server is notified when the result is ready. See Webhooks.

---

Minimal enhancement example (Node.js)

import { GraphQLClient, gql } from 'graphql-request';

const client = new GraphQLClient('https://api.viesus.cloud/graphql', {
  headers: { 'x-api-key': process.env.VIESUS_API_KEY },
});

const UPLOAD = gql`
  mutation ($url: String!) {
    createUploadFromUrl(input: { url: $url }) { id }
  }
`;

const ENHANCE = gql`
  mutation ($uploadId: ID!) {
    createEnhancedImage(uploadId: $uploadId, input: { mode: ENHANCE }) { id status }
  }
`;

const STATUS = gql`
  query ($id: ID!) {
    enhancedImage(id: $id) { status fullUrl errorCode }
  }
`;

async function enhance(imageUrl) {
  const { createUploadFromUrl } = await client.request(UPLOAD, { url: imageUrl });
  const { createEnhancedImage } = await client.request(ENHANCE, { uploadId: createUploadFromUrl.id });

  let result;
  do {
    await new Promise(r => setTimeout(r, 3000));
    result = (await client.request(STATUS, { id: createEnhancedImage.id })).enhancedImage;
  } while (result.status === 'QUEUED');

  if (result.status === 'ERROR') throw new Error(`Error: ${result.errorCode}`);
  return result.fullUrl;
}