Enhance PDFs

Enhance PDFs via VIESUS Cloud. Analysis phase, enhancement parameters, DPI limits by subscription tier, and webhook events.

PDF enhancement works differently from image enhancement. Before any enhancement can be triggered, the PDF must go through an analysis phase that identifies all embedded images and calculates the credit cost. Analysis starts automatically after upload.

---

1

Upload the PDF

Upload using either method from Uploading. Save the returned id.

mutation {
  createUploadFromUrl(
    input: { url: "https://example.com/photobook.pdf" }
  ) {
    id
    status
  }
}

Analysis begins automatically after the upload completes.

2

Wait for analysis

Query the upload to check analysis progress:

query {
  upload(id: "your-upload-id") {
    id
    subStatus
    metadata
  }
}

Analysis status values

subStatus	Meaning	Action
METADATA_ANALYZING	Analysis in progress	Wait or use a webhook
METADATA_ANALYZED_SUCCESSFULLY	Ready for enhancement	Proceed to the next step
METADATA_ANALYZED_FAILED	Analysis failed	Retry with analyzePdf mutation

Analysis results

When analysis succeeds, the metadata field contains:

• Total image count in the PDF
• Number of images eligible for color enhancement
• Number of images eligible for resizing/upscaling
• Estimated credit cost for different enhancement combinations

Review the credit estimate before triggering enhancement — especially for large PDFs.

Does analysis distinguish customer photos from embedded artwork?

No. Analysis doesn't classify embedded raster images by content type. It identifies every raster image in the PDF and reports eligibility based on technical criteria (such as image size and color variation) — not on whether the image is a customer photo or design artwork. There's currently no way to flag individual images for exclusion; enhancement applies to all images that meet the eligibility criteria. If a PDF mixes customer photos with raster artwork you don't want enhanced, review the eligible-image counts from analysis before calling createEnhancedImage.

Re-trigger analysis (on failure)

mutation {
  analyzePdf(uploadId: "your-upload-id") {
    success
  }
}

Expected response when the re-analysis request is successfully queued:

{ "success": true }

If analysis fails repeatedly after multiple re-analysis attempts, this may indicate file format incompatibility, corrupted document content, or system processing limitations. Contact VIESUS technical support with your upload ID and file details for further investigation.

3

Enhance the PDF

Once subStatus is METADATA_ANALYZED_SUCCESSFULLY:

mutation {
  createEnhancedImage(
    uploadId: "your-upload-id"
    input: {
      targetResolution: 300
      upscalingThreshold: 1.2
    }
  ) {
    id
    status
    fullUrl
    filename
    viesusDuration
  }
}

Parameters for PDF enhancement

Parameter	Type	Description
targetResolution	Decimal	Target output DPI for embedded images
upscalingThreshold	Decimal	Minimum scale factor required before upscaling is applied to an image; 1.2 = only upscale images that need more than 20% enlargement
customColorConfig	CustomColorConfigInput	Manual color adjustments

PDF enhancement supports only these three parameters. The full image enhancement parameter set (noise reduction, face details, etc.) does not apply to PDFs.

4

Retrieve the enhanced PDF

Check status using the id from the previous step:

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

When status is FINISHED, the enhanced PDF is available at fullUrl.

---

Upscaling limits by subscription

PDF enhancement output resolution is capped by subscription tier:

Subscription	Maximum output resolution
Free	300 DPI
Basic	600 DPI
Business	1,200 DPI

---

Webhook events for PDFs

Rather than polling, use webhooks to receive push notifications for both events:

Analysis complete — upload.sub_status_update:

{
  "id": "eventId",
  "event": "upload.sub_status_update",
  "data": {
    "id": "uploadId",
    "status": "UPLOAD_FINISHED",
    "subStatus": "METADATA_ANALYZED_SUCCESSFULLY",
    "metadata": {
      "statistics": {},
      "totalCredits": 78
    }
  },
  "created": "2025-05-15T14:12:37.501Z"
}

Enhancement complete — same event structure with status: FINISHED on the enhancedImage.

See Webhooks for setup and signature verification.

---

End-to-end Node.js example

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

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

async function enhancePdf(pdfUrl) {
  // Upload
  const { createUploadFromUrl } = await client.request(gql`
    mutation { createUploadFromUrl(input: { url: "${pdfUrl}" }) { id } }
  `);
  const uploadId = createUploadFromUrl.id;

  // Wait for analysis
  let upload;
  do {
    await new Promise(r => setTimeout(r, 5000));
    upload = (await client.request(gql`
      query { upload(id: "${uploadId}") { subStatus metadata } }
    `)).upload;
  } while (upload.subStatus === 'METADATA_ANALYZING');

  if (upload.subStatus !== 'METADATA_ANALYZED_SUCCESSFULLY') {
    throw new Error(`Analysis failed: ${upload.subStatus}`);
  }

  console.log('Estimated credits:', JSON.parse(upload.metadata).totalCredits);

  // Enhance
  const { createEnhancedImage } = await client.request(gql`
    mutation {
      createEnhancedImage(
        uploadId: "${uploadId}",
        input: { targetResolution: 300, upscalingThreshold: 1.2 }
      ) { id }
    }
  `);

  // Wait for completion
  let result;
  do {
    await new Promise(r => setTimeout(r, 10000));
    result = (await client.request(gql`
      query { enhancedImage(id: "${createEnhancedImage.id}") { status fullUrl errorCode } }
    `)).enhancedImage;
  } while (result.status === 'QUEUED');

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