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

# Create a conversion

> Conversions cost $0.02 per 1,000 words in the converted output, with a $0.10 minimum. The charge is proportional per word rather than rounded to started 1,000-word units. Managed PDF/image scanning inference is included; when BYOK is selected, the provider separately bills its own inference. Vision conversion rasterizes pages in order and sends up to 10 distinct page images per model request.

This call returns an admission receipt. Poll the get endpoint until work stops, then download the artifacts. See [job lifecycle](/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 openapi/revise-api.json POST /v1/convert
openapi: 3.1.0
info:
  title: Revise API
  version: 0.1.0
  description: >-
    Queued document prompting and file conversion. Conversion supports the same
    formats as revise.io/converter, including semantic PDF/image scanning. USD
    responses are exact decimal strings. Same-origin downloads require Bearer
    auth. Account provider keys (BYOK) are pinned at admission. Request content
    expires 24 hours after terminal completion; encrypted artifacts use compact
    JWE RSA-OAEP-256/A256GCM.
servers:
  - url: https://revise.io/api
security:
  - apiKey: []
paths:
  /v1/convert:
    post:
      summary: Queue a file conversion
      description: >-
        Conversions cost $0.02 per 1,000 words in the converted output, with a
        $0.10 minimum. The charge is proportional per word rather than rounded
        to started 1,000-word units. Managed PDF/image scanning inference is
        included; when BYOK is selected, the provider separately bills its own
        inference. Vision conversion rasterizes pages in order and sends up to
        10 distinct page images per model request.
      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'
        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: >-
        The base fee is graduated per API account each UTC calendar month:
        requests 1-1000 $0.05, 1001-5000 $0.035, 5001-10000 $0.02, then $0.01.
        Each newly accepted request counts once across all keys, including later
        failures/cancellations. Retries with the same idempotency key do not
        count again. The rate is pinned on admission; CPU and inference rates do
        not change with volume.
      type: object
      properties:
        max_platform_cost_usd:
          description: >-
            Soft spending threshold. New model calls stop when observed platform
            cost reaches this amount; active responses and tools finish and are
            billed in full.
          oneOf:
            - type: string
              pattern: ^[0-9]+(\.[0-9]{1,9})?$
            - type: number
              minimum: 0
              maximum: 1000000
        max_inference_cost_usd:
          description: >-
            Soft spending threshold checked against reported inference cost,
            including premium and search. No predicted cost is reserved; the
            last response may exceed this amount and is billed in full. On a
            request billed by the account's own provider key the threshold
            meters the provider's list-price spend instead; Revise still charges
            nothing for that inference.
          oneOf:
            - type: string
              pattern: ^[0-9]+(\.[0-9]{1,9})?$
            - type: number
              minimum: 0
              maximum: 1000000
        max_seconds:
          type: integer
          minimum: 120
          maximum: 3600
          description: >-
            Soft work budget in seconds (minimum 120). Active model responses
            finish normally; no new turn starts after the deadline, and exports
            may finish later.
      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
        model:
          type: string
        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
    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
        content_type:
          type: string
        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: >-
            Same-origin path. Requires the same Bearer API key; never a public
            signed link in this local build.
        input_eligible:
          type: boolean
          description: >-
            False for encrypted artifacts; they must be decrypted locally and
            re-uploaded.
        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
      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 output-word 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:
            output_words:
              type: integer
              minimum: 0
            rate_usd_per_1000_words:
              type: string
              pattern: ^-?[0-9]+\.[0-9]{9}$
              example: '0.020000000'
            minimum_fee_usd:
              type: string
              pattern: ^-?[0-9]+\.[0-9]{9}$
              example: '0.100000000'
          required:
            - output_words
            - rate_usd_per_1000_words
            - minimum_fee_usd
          additionalProperties: false
          description: >-
            Present on settled conversion receipts. The base_fee_usd cost item
            is max(minimum_fee_usd, output_words multiplied by the per-word
            rate).
        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-v5-monthly-fees
        platform:
          tool_cpu_seconds: '1.000000'
          tool_cpu_rate_usd_per_second: '0.001000000'
        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.061000000'
          itemized:
            base_fee_usd: '0.050000000'
            cpu_fee_usd: '0.001000000'
            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>.

````