> ## Documentation Index
> Fetch the complete documentation index at: https://revise.io/developer/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

See [conversion formats and limits](/developer/docs/developer/docs/revise-api/conversions) 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](/developer/docs/developer/docs/revise-api/jobs).

## TypeScript

```ts theme={null}
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" },
);
```


## OpenAPI

````yaml developer/docs/openapi/revise-api.json POST /v1/convert
openapi: 3.1.0
info:
  title: Revise API
  version: 0.1.0
  description: >-
    Asynchronous document prompts and format conversions. Submit a job, poll its
    receipt or receive a webhook, then download its artifacts. USD amounts are
    exact decimal strings. Job content expires 24 hours after terminal
    completion. All account endpoints require a bearer API key.
servers:
  - url: https://revise.io/api
security:
  - apiKey: []
paths:
  /v1/convert:
    post:
      summary: Queue a file conversion
      description: >-
        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.
      operationId: createConversion
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversionRequest'
      responses:
        '202':
          description: Queued conversion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversion'
          headers:
            Location:
              description: Account-authenticated path to retrieve this resource.
              schema:
                type: string
            Idempotent-Replayed:
              description: Present with value true on an idempotent replay.
              schema:
                type: string
                enum:
                  - 'true'
            Retry-After:
              description: Suggested delay before polling, in seconds.
              schema:
                type: string
                example: '1'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ConversionRequest:
      type: object
      additionalProperties: false
      required:
        - input
        - output
      properties:
        input:
          type: object
          additionalProperties: false
          required:
            - file_id
          properties:
            file_id:
              type: string
        output:
          type: object
          additionalProperties: false
          required:
            - format
          properties:
            format:
              enum:
                - docx
                - pdf
                - md
                - html
                - txt
        limits:
          $ref: '#/components/schemas/Limits'
        inference:
          $ref: '#/components/schemas/InferenceRequest'
        metadata:
          $ref: '#/components/schemas/Metadata'
        output_encryption:
          $ref: '#/components/schemas/OutputEncryption'
        retention:
          $ref: '#/components/schemas/RetentionOptions'
    Conversion:
      type: object
      additionalProperties: true
      required:
        - id
        - object
        - status
        - mode
        - input
        - output
        - metadata
        - created_at
        - output_encrypted
        - usage
        - completed_at
        - content_expires_at
        - content_deleted_at
        - error
      properties:
        id:
          type: string
        object:
          const: conversion
        status:
          enum:
            - queued
            - running
            - succeeded
            - failed
            - cancelled
        mode:
          enum:
            - deterministic
            - vision
            - ''
          description: Empty after request content has been deleted.
        input:
          type: object
          properties:
            file_id:
              type: string
            format:
              enum:
                - pdf
                - docx
                - md
                - html
                - txt
                - rtf
                - odt
                - image
                - ''
              description: Empty after request content has been deleted.
            filename:
              type: string
            bytes:
              type: integer
            sha256:
              type: string
          required:
            - file_id
            - format
            - filename
            - bytes
            - sha256
        output:
          type: object
          properties:
            format:
              enum:
                - docx
                - pdf
                - md
                - html
                - txt
                - ''
              description: Empty after request content has been deleted.
            artifact:
              anyOf:
                - $ref: '#/components/schemas/Artifact'
                - type: 'null'
          required:
            - format
            - artifact
        output_encrypted:
          type: boolean
        metadata:
          $ref: '#/components/schemas/Metadata'
        usage:
          anyOf:
            - $ref: '#/components/schemas/Usage'
            - type: 'null'
        created_at:
          type: string
          format: date-time
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
        content_expires_at:
          type:
            - string
            - 'null'
          format: date-time
        content_deleted_at:
          type:
            - string
            - 'null'
          format: date-time
        error:
          anyOf:
            - type: object
              properties:
                code:
                  type: string
                message:
                  type: string
                details:
                  type: object
                  additionalProperties: true
              required:
                - code
                - message
              additionalProperties: false
            - type: 'null'
        retention:
          $ref: '#/components/schemas/RetentionOptions'
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
          required:
            - code
            - message
          additionalProperties: false
      required:
        - error
      additionalProperties: false
    Limits:
      description: >-
        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.
      type: object
      properties:
        max_platform_cost_usd:
          description: >-
            Platform spending threshold. Must cover the applicable
            base/conversion fee, or one scan page. A scan checks its full page
            fee before inference. For prompts, no new model call starts once
            observed platform spend reaches this threshold; active work may
            exceed it. Omit for no per-request spending limit. Must be greater
            than zero when supplied.
          oneOf:
            - type: string
              pattern: ^(?=[0-9.]*[1-9])[0-9]+(\.[0-9]{1,9})?$
            - type: number
              maximum: 1000000
              exclusiveMinimum: 0
        max_inference_cost_usd:
          description: >-
            Soft inference threshold, including managed prompt premium and
            search. Active responses can exceed it. With your own provider key
            it meters provider list-price spend, while Revise charges no
            inference fee. For managed scans, scan inference is included in the
            page fee but remains subject to this threshold. Omit for no
            per-request spending limit. Must be greater than zero when supplied.
          oneOf:
            - type: string
              pattern: ^(?=[0-9.]*[1-9])[0-9]+(\.[0-9]{1,9})?$
            - type: number
              maximum: 1000000
              exclusiveMinimum: 0
        max_seconds:
          type: integer
          minimum: 120
          maximum: 3600
          description: >-
            Work budget in seconds, starting when a worker begins, excluding
            queue time. Prompts stop new turns at the deadline; active responses
            and exports can finish later.
          default: 900
      required: []
      additionalProperties: false
      example:
        max_platform_cost_usd: '2.000000000'
        max_inference_cost_usd: '3.000000000'
        max_seconds: 900
    InferenceRequest:
      type: object
      properties:
        provider:
          enum:
            - openai
            - anthropic
            - xai
            - gemini
          description: >-
            Public provider ID. Omit for the API default on a new conversation,
            or inherit from previous_prompt_id.
        model:
          type: string
          description: >-
            Exact model ID from /v1/models, or default. Omitting it selects the
            provider default, except when inherited from a predecessor.
        billing:
          enum:
            - revise
            - provider
          description: >-
            Which party pays for inference. Omitted or "revise" is automatic:
            the account's stored key for the resolved provider is used when
            present (billed by the provider, no Revise inference charge),
            otherwise managed inference applies. "provider" requires a stored
            key for the resolved provider and fails admission with
            provider_key_required instead of falling back. Provider resolution
            includes defaults and predecessor inheritance, so an omitted
            provider still uses the account key.
      required: []
      additionalProperties: false
    Metadata:
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 512
      propertyNames:
        minLength: 1
        maxLength: 64
      example:
        customer: acme
        environment: production
      description: >-
        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.
    OutputEncryption:
      type: object
      additionalProperties: false
      required:
        - format
        - public_key_pem
      properties:
        format:
          type: string
          enum:
            - jwe
        public_key_pem:
          type: string
          maxLength: 16384
          description: >-
            RSA SubjectPublicKeyInfo PEM (BEGIN PUBLIC KEY), 2048–8192 bits.
            Private keys, certificates and key URLs are rejected.
      description: >-
        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.
    RetentionOptions:
      type: object
      additionalProperties: false
      properties:
        delete_after_webhook_id:
          type: string
          pattern: ^wh_[0-9a-f-]{36}$
          description: >-
            Account-owned endpoint subscribed to prompt.completed or
            conversion.completed, matching the request kind. Its successful
            acknowledgement deletes request content and ephemeral source.
            Download everything before returning 2xx.
      required:
        - delete_after_webhook_id
    Artifact:
      type: object
      properties:
        id:
          type: string
        prompt_id:
          type: string
        conversion_id:
          type: string
        format:
          enum:
            - docx
            - pdf
            - md
            - html
            - txt
        filename:
          type: string
          description: >-
            Original plaintext filename, even when encrypted. Encrypted
            downloads append .jwe.
        content_type:
          type: string
          description: >-
            Original plaintext MIME type. Encrypted downloads use
            application/jose.
        variant:
          enum:
            - tracked_changes
            - clean
            - converted
        sha256:
          type: string
          description: >-
            SHA-256 of the exact downloadable bytes (ciphertext for encrypted
            artifacts).
        bytes:
          type: integer
          description: >-
            Size of the downloadable bytes, including JWE encoding overhead when
            encrypted.
        download_url:
          type: string
          description: >-
            Account-authenticated API path. The endpoint may redirect to signed
            storage; never forward bearer credentials to storage.
        input_eligible:
          type: boolean
          description: >-
            True only for an unexpired, undeleted, unencrypted prompt artifact.
            Conversion artifacts are not directly reusable; download and upload
            them first.
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        encryption:
          $ref: '#/components/schemas/ArtifactEncryption'
        deleted_at:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - format
        - filename
        - content_type
        - variant
        - sha256
        - bytes
        - download_url
        - input_eligible
        - expires_at
        - deleted_at
      additionalProperties: false
    Usage:
      type: object
      properties:
        pricing_version:
          type: string
        platform:
          type: object
          properties:
            tool_cpu_seconds:
              type: string
              pattern: ^[0-9]+\.[0-9]{6}$
              example: '1.250000'
            tool_cpu_rate_usd_per_second:
              type: string
              pattern: ^-?[0-9]+\.[0-9]{9}$
              example: '0.050000000'
          required:
            - tool_cpu_seconds
            - tool_cpu_rate_usd_per_second
          additionalProperties: false
        inference:
          type: object
          properties:
            billed_by:
              enum:
                - revise
                - provider
              description: >-
                "provider" when the account's own key paid the supplier:
                inference_fee_usd is then zero, token counts are still reported,
                and no supplier amount is exposed.
            input_tokens:
              type: integer
              minimum: 0
            cached_input_tokens:
              type: integer
              minimum: 0
            cache_creation_input_tokens:
              type: integer
              minimum: 0
            output_tokens:
              type: integer
              minimum: 0
            web_search_requests:
              type: integer
              minimum: 0
            web_search_unit:
              type: string
              enum:
                - calls
                - queries
                - grounded_prompts
          required:
            - billed_by
          additionalProperties: false
          description: >-
            Includes model input, cache reads/writes, output and reasoning,
            compaction, and native web/X search or Google grounding. Search
            units depend on provider. Provider-reported usage counts are omitted
            on older receipts. For conversions, managed scan inference is
            included in the per-page conversion fee, so inference_fee_usd is
            zero. Aggregate token counts do not imply a single inference rate;
            historical per-category rates are not available in this receipt.
        conversion:
          type: object
          properties:
            unit:
              enum:
                - conversion
                - page
                - word
              description: >-
                conversion: flat fee for a non-scanned input. page: PDF/image
                pages actually scanned. word: only on conversions admitted under
                the superseded local-v7-conversion-words pricing.
            quantity:
              type: integer
              minimum: 0
              description: >-
                Units billed: 1 (or 0 if unbilled) for conversion, scanned pages
                for page, output words for word.
            unit_price_usd:
              type: string
              pattern: ^-?[0-9]+\.[0-9]{9}$
              example: '0.020000000'
            minimum_fee_usd:
              type: string
              pattern: ^-?[0-9]+\.[0-9]{9}$
              description: Only present for unit word.
          required:
            - unit
            - quantity
            - unit_price_usd
          additionalProperties: false
          description: >-
            Conversion billing details retained after content deletion. For
            billed work, base_fee_usd is quantity × unit_price_usd (historical
            word pricing applies a minimum). Read settled cost for the actual
            charge.
        cost:
          $ref: '#/components/schemas/Cost'
      required:
        - pricing_version
        - platform
        - inference
        - cost
      additionalProperties: false
      description: >-
        Customer-facing settled charges and usage. Supplier costs, margins and
        internal reconciliation diagnostics are not exposed. Historical charges
        are never recalculated using current prices.
      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'
    ArtifactEncryption:
      type: object
      additionalProperties: false
      required:
        - format
        - alg
        - enc
        - key_id
      properties:
        format:
          type: string
          enum:
            - jwe
        alg:
          type: string
          enum:
            - RSA-OAEP-256
        enc:
          type: string
          enum:
            - A256GCM
        key_id:
          type: string
          description: >-
            Base64url SHA-256 JWK thumbprint of the recipient public key
            (RFC7638).
    Cost:
      type: object
      additionalProperties: false
      required:
        - total_usd
        - itemized
      properties:
        total_usd:
          type: string
          pattern: ^[0-9]+\.[0-9]{9}$
          example: '0.305000000'
        itemized:
          type: object
          additionalProperties: false
          required:
            - base_fee_usd
            - cpu_fee_usd
            - inference_fee_usd
          properties:
            base_fee_usd:
              type: string
              pattern: ^[0-9]+\.[0-9]{9}$
              example: '0.250000000'
            cpu_fee_usd:
              type: string
              pattern: ^[0-9]+\.[0-9]{9}$
              example: '0.005000000'
            inference_fee_usd:
              type: string
              pattern: ^[0-9]+\.[0-9]{9}$
              example: '0.050000000'
      example:
        total_usd: '0.305000000'
        itemized:
          base_fee_usd: '0.250000000'
          cpu_fee_usd: '0.005000000'
          inference_fee_usd: '0.050000000'
      description: >-
        Settled customer charges. Itemized base, CPU and inference fees are
        disjoint and sum exactly to total_usd. Inference includes model
        processing and web search. No overlapping platform subtotal. Balances
        and limits are separate from cost.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        Revise API key from https://revise.io/console/api-keys. Send
        Authorization: Bearer <key>.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.