Models Reference

This page lists the main public response models used by the API.

ErrorResponse

All error responses share this envelope. Some errors include additional context fields.

Additional fields may appear depending on the error code (e.g. sourceFormat, supportedTargets on convert.unsupported_format_pair). See Errors for full examples.

Example:

{
  "error": "convert.unsupported_format_pair",
  "detail": "Conversion from 'jpg' to 'mp3' is not supported.",
  "sourceFormat": "jpg",
  "targetFormat": "mp3",
  "supportedTargets": ["avif", "ico", "pdf", "png", "webp"]
}

JobAcceptedResponse (POST /convert)

Example — HEIC-to-JPG conversion accepted:

{
  "id": "0195e2a0-1234-7000-8000-000000000001",
  "status": "Queued",
  "creditCost": 1
}

JobStatusResponse (GET /convert/job/{id})

For jobs that are still Queued or Running, progress.percent is 0 and metrics.inputBytes / metrics.outputBytes are 0. The metrics.creditCost is always populated (cost is determined at submission time). The error object is only populated for Failed jobs. The output object is only populated for Succeeded jobs whose artifacts haven't expired.

Example — Succeeded HEIC-to-JPG job (single output):

{
  "id": "0195e2a0-1234-7000-8000-000000000001",
  "status": "Succeeded",
  "progress": {
    "percent": 100,
    "phase": null
  },
  "metrics": {
    "inputBytes": 2458624,
    "outputBytes": 1024000,
    "creditCost": 1
  },
  "error": null,
  "output": {
    "fileName": "vacation-photo.jpg",
    "contentType": "image/jpeg",
    "fileCount": 1
  }
}

Example — Running job (processing in progress):

{
  "id": "0195e2a0-1234-7000-8000-000000000001",
  "status": "Running",
  "progress": {
    "percent": 0,
    "phase": null
  },
  "metrics": {
    "inputBytes": 0,
    "outputBytes": 0,
    "creditCost": 1
  },
  "error": null,
  "output": null
}

Example — Succeeded PDF-to-JPG job (multi-output, downloaded as ZIP):

{
  "id": "0195e2a0-1234-7000-8000-000000000002",
  "status": "Succeeded",
  "progress": {
    "percent": 100,
    "phase": null
  },
  "metrics": {
    "inputBytes": 5242880,
    "outputBytes": 12582912,
    "creditCost": 5
  },
  "error": null,
  "output": {
    "fileName": "convert.fast-pdf-to-jpg-annual-report-50-outputs.zip",
    "contentType": "application/zip",
    "fileCount": 50
  }
}

JobOutputSummary

Describes the output file(s) of a succeeded job. For single-output jobs, shows the actual file's name and content type. For multi-output jobs (e.g. PDF-to-JPG pages), shows the computed ZIP filename and application/zip.

Use fileName to set the -o argument in cURL or the OutFile parameter in PowerShell when downloading.

CostingInfo

Describes the credit cost strategy for a converter. Appears inside ConversionItem and ConversionEdge.

Calculating credits

All variable strategies use the same formula:

credits = ceil(quantity / increment) × baseCost

Fractional increments always round up — a 1-page PDF with increment: 5 still costs 1× baseCost. Use GET /convert/estimate/{from}/{to} for server-side calculation.

Examples:

{
  "strategy": "Fixed",
  "baseCost": 1,
  "increment": null,
  "incrementUnit": null,
  "displaySuffix": "each",
  "costVariants": null
}

{
  "strategy": "PerMegabyte",
  "baseCost": 1,
  "increment": 5,
  "incrementUnit": "mb",
  "displaySuffix": "per 5 MB",
  "costVariants": null
}

{
  "strategy": "PerPage",
  "baseCost": 1,
  "increment": 5,
  "incrementUnit": "pages",
  "displaySuffix": "per 5 pages",
  "costVariants": null
}

{
  "strategy": "PerMinute",
  "baseCost": 1,
  "increment": 5,
  "incrementUnit": "minutes",
  "displaySuffix": "per 5 minutes",
  "costVariants": null
}

GetConversionsResponse (GET /convert/conversions)

Top-level fields:

ConversionItem

Appears in the top-level conversions array. Groups a converter's full capabilities including all accepted input/output formats.

ConversionEdge

A single source→target pair for direct lookup. Appears inside sourceFormatTo values — use this when you already know the source format and want to find available targets.

Example — Truncated response showing one converter and one sourceFormatTo edge:

{
  "conversions": [
    {
      "job": "image.heic-to-jpg",
      "category": "images",
      "costing": {
        "strategy": "PerMegabyte",
        "baseCost": 1,
        "increment": 5,
        "incrementUnit": "mb",
        "displaySuffix": "per 5 MB",
        "costVariants": null
      },
      "endpoint": "/api/convert",
      "inputFormats": ["heic", "heif"],
      "outputFormats": ["jpg"],
      "maxFileSizeBytes": 1073741824,
      "maxConcurrentJobs": 6,
      "maxPages": null,
      "maxDurationMinutes": null,
      "maxBatchSizeBytes": 10737418240
    }
  ],
  "sourceFormatTo": {
    "heic": [
      {
        "sourceFormat": "heic",
        "targetFormat": "jpg",
        "job": "image.heic-to-jpg",
        "endpoint": "/api/convert",
        "category": "images",
        "costing": {
          "strategy": "PerMegabyte",
          "baseCost": 1,
          "increment": 5,
          "incrementUnit": "mb",
          "displaySuffix": "per 5 MB",
          "costVariants": null
        },
        "maxFileSizeBytes": 1073741824,
        "maxConcurrentJobs": 6,
        "maxPages": null,
        "maxDurationMinutes": null
      }
    ]
  },
  "maxFileSizeBytes": 2147483648,
  "maxConcurrentJobs": 6,
  "maxBatchFiles": 200
}

For a multi-converter example showing all four costing strategies, see List Conversions.

ConvertFastEntitlementsResponse (GET /convert/entitlements/me)

Example:

{
  "userId": "0195e2a0-1234-7000-8000-000000000099",
  "organizationId": "0195e2a0-1234-7000-8000-000000000050",
  "planId": "pro",
  "planName": "Pro",
  "accessDisplayName": "Pro",
  "totalCredits": 4850,
  "tier": "pro",
  "dailyLimit": null,
  "dailyUsed": null,
  "resetDate": null
}