Conversions

Create a conversion

Convert one uploaded file to docx, pdf, md, html, or txt. Same-format conversion is rejected. DOCX, Markdown, HTML, text, RTF, and ODT use deterministic conversion at $0.005 each. PDF and image inputs use semantic scanning:$ 0.02 per page with managed inference on the default OpenAI model, or $0.005 per page plus provider inference when using your own OpenAI key. Only your own key permits another catalogued OpenAI model. Deterministic conversions reject nonempty inference settings.

Uploads are limited to 18 MiB, PDFs to 100 pages, and output to 50 MiB before encryption. There is no default spending cap; an explicitly set insufficient page budget fails with conversion_limit_exceeded before inference. PDF processing errors include pdf_page_limit_exceeded, pdf_password_protected, invalid_pdf, and empty_pdf. These validation failures are unbilled. Cancellation or customer limits can incur charges for work already performed; read settled usage. Conversions have no additional CPU or Revise inference fee and do not count toward prompt base-fee tiers.

POST

convert

Queue a file conversion

curl --request POST \
  --url https://revise.io/api/v1/convert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "input": {
    "file_id": "<string>"
  },
  "output": {},
  "limits": {
    "max_platform_cost_usd": "2.000000000",
    "max_inference_cost_usd": "3.000000000",
    "max_seconds": 900
  },
  "inference": {
    "model": "<string>"
  },
  "metadata": {
    "customer": "acme",
    "environment": "production"
  }
}
'

import requests

url = "https://revise.io/api/v1/convert"

payload = {
    "input": { "file_id": "<string>" },
    "output": {},
    "limits": {
        "max_platform_cost_usd": "2.000000000",
        "max_inference_cost_usd": "3.000000000",
        "max_seconds": 900
    },
    "inference": { "model": "<string>" },
    "metadata": {
        "customer": "acme",
        "environment": "production"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    input: {file_id: '<string>'},
    output: {},
    limits: {
      max_platform_cost_usd: '2.000000000',
      max_inference_cost_usd: '3.000000000',
      max_seconds: 900
    },
    inference: {model: '<string>'},
    metadata: {customer: 'acme', environment: 'production'}
  })
};

fetch('https://revise.io/api/v1/convert', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://revise.io/api/v1/convert",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => [
        'file_id' => '<string>'
    ],
    'output' => [
        
    ],
    'limits' => [
        'max_platform_cost_usd' => '2.000000000',
        'max_inference_cost_usd' => '3.000000000',
        'max_seconds' => 900
    ],
    'inference' => [
        'model' => '<string>'
    ],
    'metadata' => [
        'customer' => 'acme',
        'environment' => 'production'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://revise.io/api/v1/convert"

	payload := strings.NewReader("{\n  \"input\": {\n    \"file_id\": \"<string>\"\n  },\n  \"output\": {},\n  \"limits\": {\n    \"max_platform_cost_usd\": \"2.000000000\",\n    \"max_inference_cost_usd\": \"3.000000000\",\n    \"max_seconds\": 900\n  },\n  \"inference\": {\n    \"model\": \"<string>\"\n  },\n  \"metadata\": {\n    \"customer\": \"acme\",\n    \"environment\": \"production\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://revise.io/api/v1/convert")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": {\n    \"file_id\": \"<string>\"\n  },\n  \"output\": {},\n  \"limits\": {\n    \"max_platform_cost_usd\": \"2.000000000\",\n    \"max_inference_cost_usd\": \"3.000000000\",\n    \"max_seconds\": 900\n  },\n  \"inference\": {\n    \"model\": \"<string>\"\n  },\n  \"metadata\": {\n    \"customer\": \"acme\",\n    \"environment\": \"production\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://revise.io/api/v1/convert")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": {\n    \"file_id\": \"<string>\"\n  },\n  \"output\": {},\n  \"limits\": {\n    \"max_platform_cost_usd\": \"2.000000000\",\n    \"max_inference_cost_usd\": \"3.000000000\",\n    \"max_seconds\": 900\n  },\n  \"inference\": {\n    \"model\": \"<string>\"\n  },\n  \"metadata\": {\n    \"customer\": \"acme\",\n    \"environment\": \"production\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "object": "conversion",
  "status": "queued",
  "mode": "deterministic",
  "input": {
    "file_id": "<string>",
    "format": "pdf",
    "filename": "<string>",
    "bytes": 123,
    "sha256": "<string>"
  },
  "output": {
    "format": "docx",
    "artifact": {
      "id": "<string>",
      "format": "docx",
      "filename": "<string>",
      "content_type": "<string>",
      "variant": "tracked_changes",
      "sha256": "<string>",
      "bytes": 123,
      "download_url": "<string>",
      "input_eligible": true,
      "expires_at": "2023-11-07T05:31:56Z",
      "deleted_at": "2023-11-07T05:31:56Z",
      "prompt_id": "<string>",
      "conversion_id": "<string>",
      "encryption": {
        "format": "jwe",
        "alg": "RSA-OAEP-256",
        "enc": "A256GCM",
        "key_id": "<string>"
      }
    }
  },
  "output_encrypted": true,
  "metadata": {
    "customer": "acme",
    "environment": "production"
  },
  "usage": {
    "pricing_version": "local-v8-conversion-pages",
    "platform": {
      "tool_cpu_seconds": "1.000000",
      "tool_cpu_rate_usd_per_second": "0.050000000"
    },
    "inference": {
      "billed_by": "revise",
      "input_tokens": 1200,
      "cached_input_tokens": 400,
      "cache_creation_input_tokens": 0,
      "output_tokens": 200,
      "web_search_requests": 1,
      "web_search_unit": "calls"
    },
    "cost": {
      "total_usd": "0.110000000",
      "itemized": {
        "base_fee_usd": "0.050000000",
        "cpu_fee_usd": "0.050000000",
        "inference_fee_usd": "0.010000000"
      }
    }
  },
  "created_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "content_expires_at": "2023-11-07T05:31:56Z",
  "content_deleted_at": "2023-11-07T05:31:56Z",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "retention": {
    "delete_after_webhook_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

See conversion formats and limits for integration guidance. This call returns an admission receipt. Poll the get endpoint until work stops, then inspect the result and download its artifacts. See job lifecycle.

TypeScript

import { ReviseClient } from "@reviseio/api";

const revise = new ReviseClient({ apiKey: process.env.REVISE_API_KEY! });
const result = await revise.conversions.create(
  { input: { file_id: "file_id" }, output: { format: "pdf" } },
  { idempotencyKey: "convert-42" },
);

Authorizations

Authorization

string

header

required

Revise API key from https://revise.io/console/api-keys. Send Authorization: Bearer .

Headers

Idempotency-Key

string

required

Required string length: 1 - 200

Body

application/json

input

object

required

Show child attributes

output

object

required

Show child attributes

limits

object

Optional execution and spending thresholds. Spending limits are opt-in: omitted cost limits are unlimited. The time limit defaults to 900 seconds. Prompt platform cost is base fee plus tool CPU; conversion platform cost is its flat/page fee. Prompt cost limits may each be at most $500,000; conversion cost limits may each be at most $1,000,000. These thresholds do not reserve account credit.

Show child attributes

Example:

{
  "max_platform_cost_usd": "2.000000000",
  "max_inference_cost_usd": "3.000000000",
  "max_seconds": 900
}

inference

object

Show child attributes

metadata

object

Up to 16 string values for application attribution. Keys are 1–64 UTF-8 bytes; values at most 512 UTF-8 bytes. Metadata is deleted with request content; persist your own job mapping for long-term attribution.

Show child attributes

Example:

{
  "customer": "acme",
  "environment": "production"
}

output_encryption

object

Encrypt exported artifact bytes using compact JWE, RSA-OAEP-256 and A256GCM. Only encrypted files are downloadable. Disables prompt continuation and artifact reuse; cannot be combined with previous_prompt_id or artifact_id input. Prompts require editing or export_document=true.

Show child attributes

retention

object

Show child attributes

Response

Queued conversion

string

required

object

any

required

status

enum<string>

required

Available options:

queued,

running,

succeeded,

failed,

cancelled

mode

enum<string>

required

Empty after request content has been deleted.

Available options:

deterministic,

vision,

input

object

required

Show child attributes

output

object

required

Show child attributes

output_encrypted

boolean

required

metadata

object

required

Show child attributes

Example:

{
  "customer": "acme",
  "environment": "production"
}

usage

object | null

required

Customer-facing settled charges and usage. Supplier costs, margins and internal reconciliation diagnostics are not exposed. Historical charges are never recalculated using current prices.

Show child attributes

Example:

{
  "pricing_version": "local-v8-conversion-pages",
  "platform": {
    "tool_cpu_seconds": "1.000000",
    "tool_cpu_rate_usd_per_second": "0.050000000"
  },
  "inference": {
    "billed_by": "revise",
    "input_tokens": 1200,
    "cached_input_tokens": 400,
    "cache_creation_input_tokens": 0,
    "output_tokens": 200,
    "web_search_requests": 1,
    "web_search_unit": "calls"
  },
  "cost": {
    "total_usd": "0.110000000",
    "itemized": {
      "base_fee_usd": "0.050000000",
      "cpu_fee_usd": "0.050000000",
      "inference_fee_usd": "0.010000000"
    }
  }
}

created_at

string<date-time>

required

completed_at

string<date-time> | null

required

content_expires_at

string<date-time> | null

required

content_deleted_at

string<date-time> | null

required

error

object | null

required

Show child attributes

retention

object

Show child attributes

Queue a file conversion

curl --request POST \
  --url https://revise.io/api/v1/convert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "input": {
    "file_id": "<string>"
  },
  "output": {},
  "limits": {
    "max_platform_cost_usd": "2.000000000",
    "max_inference_cost_usd": "3.000000000",
    "max_seconds": 900
  },
  "inference": {
    "model": "<string>"
  },
  "metadata": {
    "customer": "acme",
    "environment": "production"
  }
}
'

import requests

url = "https://revise.io/api/v1/convert"

payload = {
    "input": { "file_id": "<string>" },
    "output": {},
    "limits": {
        "max_platform_cost_usd": "2.000000000",
        "max_inference_cost_usd": "3.000000000",
        "max_seconds": 900
    },
    "inference": { "model": "<string>" },
    "metadata": {
        "customer": "acme",
        "environment": "production"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    input: {file_id: '<string>'},
    output: {},
    limits: {
      max_platform_cost_usd: '2.000000000',
      max_inference_cost_usd: '3.000000000',
      max_seconds: 900
    },
    inference: {model: '<string>'},
    metadata: {customer: 'acme', environment: 'production'}
  })
};

fetch('https://revise.io/api/v1/convert', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://revise.io/api/v1/convert",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => [
        'file_id' => '<string>'
    ],
    'output' => [
        
    ],
    'limits' => [
        'max_platform_cost_usd' => '2.000000000',
        'max_inference_cost_usd' => '3.000000000',
        'max_seconds' => 900
    ],
    'inference' => [
        'model' => '<string>'
    ],
    'metadata' => [
        'customer' => 'acme',
        'environment' => 'production'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://revise.io/api/v1/convert"

	payload := strings.NewReader("{\n  \"input\": {\n    \"file_id\": \"<string>\"\n  },\n  \"output\": {},\n  \"limits\": {\n    \"max_platform_cost_usd\": \"2.000000000\",\n    \"max_inference_cost_usd\": \"3.000000000\",\n    \"max_seconds\": 900\n  },\n  \"inference\": {\n    \"model\": \"<string>\"\n  },\n  \"metadata\": {\n    \"customer\": \"acme\",\n    \"environment\": \"production\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://revise.io/api/v1/convert")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": {\n    \"file_id\": \"<string>\"\n  },\n  \"output\": {},\n  \"limits\": {\n    \"max_platform_cost_usd\": \"2.000000000\",\n    \"max_inference_cost_usd\": \"3.000000000\",\n    \"max_seconds\": 900\n  },\n  \"inference\": {\n    \"model\": \"<string>\"\n  },\n  \"metadata\": {\n    \"customer\": \"acme\",\n    \"environment\": \"production\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://revise.io/api/v1/convert")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": {\n    \"file_id\": \"<string>\"\n  },\n  \"output\": {},\n  \"limits\": {\n    \"max_platform_cost_usd\": \"2.000000000\",\n    \"max_inference_cost_usd\": \"3.000000000\",\n    \"max_seconds\": 900\n  },\n  \"inference\": {\n    \"model\": \"<string>\"\n  },\n  \"metadata\": {\n    \"customer\": \"acme\",\n    \"environment\": \"production\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "object": "conversion",
  "status": "queued",
  "mode": "deterministic",
  "input": {
    "file_id": "<string>",
    "format": "pdf",
    "filename": "<string>",
    "bytes": 123,
    "sha256": "<string>"
  },
  "output": {
    "format": "docx",
    "artifact": {
      "id": "<string>",
      "format": "docx",
      "filename": "<string>",
      "content_type": "<string>",
      "variant": "tracked_changes",
      "sha256": "<string>",
      "bytes": 123,
      "download_url": "<string>",
      "input_eligible": true,
      "expires_at": "2023-11-07T05:31:56Z",
      "deleted_at": "2023-11-07T05:31:56Z",
      "prompt_id": "<string>",
      "conversion_id": "<string>",
      "encryption": {
        "format": "jwe",
        "alg": "RSA-OAEP-256",
        "enc": "A256GCM",
        "key_id": "<string>"
      }
    }
  },
  "output_encrypted": true,
  "metadata": {
    "customer": "acme",
    "environment": "production"
  },
  "usage": {
    "pricing_version": "local-v8-conversion-pages",
    "platform": {
      "tool_cpu_seconds": "1.000000",
      "tool_cpu_rate_usd_per_second": "0.050000000"
    },
    "inference": {
      "billed_by": "revise",
      "input_tokens": 1200,
      "cached_input_tokens": 400,
      "cache_creation_input_tokens": 0,
      "output_tokens": 200,
      "web_search_requests": 1,
      "web_search_unit": "calls"
    },
    "cost": {
      "total_usd": "0.110000000",
      "itemized": {
        "base_fee_usd": "0.050000000",
        "cpu_fee_usd": "0.050000000",
        "inference_fee_usd": "0.010000000"
      }
    }
  },
  "created_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "content_expires_at": "2023-11-07T05:31:56Z",
  "content_deleted_at": "2023-11-07T05:31:56Z",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "retention": {
    "delete_after_webhook_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

Getting started

Guides

REST reference

Create a conversion

TypeScript

Authorizations

Headers

Body

Response

​TypeScript

Authorizations

Headers

Body

Response

TypeScript