# Your first conversion

[HTML](https://pdfcraft.ai/docs/getting-started/overview/)
[Site index](https://pdfcraft.ai/llms.txt)

Convert a PDF to Markdown with the Python example.


To use PDFCraft from an AI agent, see [connect your agent with MCP](https://pdfcraft.ai/docs/getting-started/mcp/).

The Transform API converts PDF files to Markdown, EPUB or translated PDF, and translates EPUB files into EPUB. Each conversion is an asynchronous task: create it, upload the source, start processing, then download the result.

## Get an API key

Sign in to [OOMOL Console](https://console.oomol.com/api-key) and create an API key. Keep it on your server or in your local environment. Processing consumes account credits; check your balance and [pricing](https://pdfcraft.ai/pricing/) before starting.

| Setting | Value |
| --- | --- |
| Base URL | `https://api.pdfcraft.ai/v1/pcc-api` |
| Authentication | `Authorization: Bearer YOUR_API_KEY` |
| Request body | JSON, except the direct file upload |

This URL requires a production API key. Website cookies and credentials for other OOMOL services cannot replace it. Send the key only in the API request’s `Authorization` header; file uploads and downloads do not require it.

## Run the Python example

You need Python 3.9 or later. No additional packages are required. Download the [example script](https://pdfcraft.ai/examples/api-quickstart.py):

```bash
curl --fail --show-error --location \
  https://pdfcraft.ai/examples/api-quickstart.py \
  --output api-quickstart.py
```

Set the key without putting it into the script. This command works in Bash and Zsh; input is hidden:

```bash
export PDF_CRAFT_API_KEY="$(
  python3 -c 'import getpass; print(getpass.getpass("API key: "))'
)"
python3 api-quickstart.py
```

The script downloads our [one-page sample PDF](https://pdfcraft.ai/examples/api-quickstart.pdf), uploads it and converts it to Markdown. It saves the task ID in `pdf-craft-task.json` so you can resume after an interruption.

The script checks the task periodically until it finishes or the timeout is reached. On success, it saves `pdf-craft-result.zip` and checks that the Markdown contains a sentence from the sample PDF. This check applies only to the supplied sample.

Markdown output is a **ZIP archive**, not a single `.md` file. Open it to read the Markdown and its accompanying resources. EPUB and PDF output are downloaded as their respective file formats.

## Resume without creating another task

If the script times out or the connection is interrupted after the task ID was saved:

```bash
python3 api-quickstart.py \
  --resume pdf-craft-task.json \
  --output pdf-craft-result.zip \
  --timeout 1200
```

Use the same account. The script checks the existing task and continues uploading, processing or downloading as needed. A failed task is not restarted. Existing output files are not overwritten; choose a new output path if necessary.

If the state file contains `creation_unknown` instead of a `uuid`, the creation response was not confirmed. Do not delete the file and immediately rerun creation. Inspect the [waiting-for-upload list](https://pdfcraft.ai/docs/api/overview/#list-tasks) to find the task before deciding to create another one.

## Use your own document

The example script uses a fixed PDF and conversion parameters. For your own files, follow the [cURL walkthrough](https://pdfcraft.ai/docs/getting-started/quickstart/), then choose [conversion and translation parameters](https://pdfcraft.ai/docs/api/conversion/).

When integrating the API, save the task’s `uuid` and launch parameters. See [task lifecycle](https://pdfcraft.ai/docs/api/lifecycle/) for recovering interrupted requests and handling expiry. Use the [API reference](https://pdfcraft.ai/docs/api/overview/) or download the [OpenAPI specification](https://pdfcraft.ai/openapi.json).