Start converting one PDF (metered)

POST

/api/v1/convert

curl --request POST \
  --url 'https://api.gevell.com/api/v1/convert?outputs=pdf%2Chtml' \
  --header 'Content-Type: application/pdf' \
  --header 'X-API-Key: <X-API-Key>' \
  --data binary

• Production

Reserves the page count at your account’s per-page rate, then starts the conversion. Settlement happens when the conversion finishes; a conversion that fails releases the reservation and charges nothing. Honours AI opt-out settings.

Send the PDF as the raw body (application/pdf, with outputs and fileName as query parameters, or X-File-Name), or JSON naming a staged upload (inputKey, from POST /api/v1/tagging/uploads) or a public fileUrl.

Idempotency-Key (8-200 characters, A-Z a-z 0-9 . _ : -): the same key from the same account returns the existing file and job (idempotentReplay: true, 202) and never reserves or charges again. A repeat while the first request is still running answers 409 IDEMPOTENT_REQUEST_IN_PROGRESS (with Retry-After). The same key with a different file size, source or outputs answers 422 IDEMPOTENCY_KEY_REUSED. A start that failed (402, 4xx) leaves the key free to retry. Keys are remembered for 24 hours. A conversion that failed stays failed under its key: start again with a new key. A start that failed before the conversion launched is retried for real.

Authorizations

• apiKey

Parameters

Header Parameters

Idempotency-Key

string

>= 8 characters <= 200 characters

Query Parameters

outputs

string

Example

pdf,html

Raw-body only. Comma-separated: html, pdf, conformance.

fileName

string

Raw-body only.

Request Body^required

string format: binary

Exactly one of inputKey or fileUrl.

object

inputKey

string

fileUrl

string format: uri

fileName

string

outputs

What to deliver. Default ["pdf","conformance"]. pdf and conformance come together; add html for the accessible HTML.

Array<string>

<= 3 items

Allowed values: html pdf conformance

Responses

202

Conversion started (or an idempotent replay). Poll GET /api/v1/convert/{fileId}.

Media typeapplication/json

object

success

boolean

data

object

fileId

string format: uuid

jobId

string format: uuid

fileName

string

status

Processing for a new job; on an idempotent replay, the file’s current status.

string

outputs

What to deliver. Default ["pdf","conformance"]. pdf and conformance come together; add html for the accessible HTML.

Array<string>

<= 3 items

Allowed values: html pdf conformance

pageCountKnown

boolean

estimatedPages

integer

estimatedWaitSeconds

integer

idempotentReplay

Present (true) when this is a repeat of an earlier start with the same Idempotency-Key.

boolean

Example

{
  "data": {
    "outputs": [
      "html"
    ]
  }
}

400

Invalid body

Media typeapplication/json

object

success

boolean

error

object

code

string

message

string

details

object

key

additional properties

any

Example

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS"
  }
}

401

Missing or invalid API key

Media typeapplication/json

object

success

boolean

error

object

code

string

message

string

details

object

key

additional properties

any

Example

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS"
  }
}

402

Insufficient balance. Nothing was stored. The message and details state the amount needed.

Media typeapplication/json

object

success

boolean

error

object

code

string

message

string

details

object

key

additional properties

any

error

object

details

Amounts are cents for pay-as-you-go accounts, pages for plan allowances.

object

balance

number

required

number

mode

string

Allowed values: paygo quota

unitPriceCents

number

nullable

estimatedPages

integer

pageCountKnown

boolean

purchaseUrl

string format: uri

Example

{
  "success": false,
  "error": {
    "details": {
      "mode": "paygo"
    }
  }
}

403

InputKey is outside your own storage prefix

Media typeapplication/json

object

success

boolean

error

object

code

string

message

string

details

object

key

additional properties

any

Example

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS"
  }
}

404

InputKey not found

Media typeapplication/json

object

success

boolean

error

object

code

string

message

string

details

object

key

additional properties

any

Example

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS"
  }
}

409

AI services disabled for the account or organisation

Media typeapplication/json

object

success

boolean

error

object

code

string

message

string

details

object

key

additional properties

any

Example

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS"
  }
}

413

PDF over 25 MB (FILE_TOO_LARGE)

Media typeapplication/json

object

success

boolean

error

object

code

string

message

string

details

object

key

additional properties

any

Example

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS"
  }
}

422

Encrypted or unreadable PDF (PAGE_COUNT_UNAVAILABLE), or IDEMPOTENCY_KEY_REUSED

Media typeapplication/json

object

success

boolean

error

object

code

string

message

string

details

object

key

additional properties

any

Example

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS"
  }
}

429

SPEND_LIMIT_EXCEEDED or DOLLAR_BUDGET_EXCEEDED

Media typeapplication/json

object

success

boolean

error

object

code

string

message

string

details

object

key

additional properties

any

Example

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS"
  }
}

500

Unexpected error

Media typeapplication/json

object

success

boolean

error

object

code

string

message

string

details

object

key

additional properties

any

Example

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS"
  }
}

503

Billing, the idempotency store or the daily system cost cap (SYSTEM_COST_CAP_REACHED) is temporarily unavailable; retry

Media typeapplication/json

object

success

boolean

error

object

code

string

message

string

details

object

key

additional properties

any

Example

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS"
  }
}