**Cost**: 13 credits per processed page.

Extract a structured, editable design tree out of one or more pages of a PDF. Each page becomes a fully-populated **`VisualElement`** tree — the same node shape as `image_to_design` — augmented with the vector / typography / transform fields that only PDFs carry.

## What this API is for

PDFs are vector documents: every paragraph, every shape, every gradient is stored as math, not pixels. This endpoint preserves that math instead of rasterizing it, so the tree you get back can be re-rendered, re-flowed, re-styled, or translated into another format without quality loss.

Typical use cases:
- **PDF → editable design**: open up an exported brochure / spec sheet / one-pager and turn it back into a Figma-like tree.
- **PDF → PPT / HTML / code**: walk the tree to emit slides, web pages, or component code. (Our own `pdf_to_ppt` builds on this.)
- **Content extraction**: pull every text run with its true font, size, and color, plus every vector shape with its actual path data.
- **Asset salvage**: re-export embedded images and vector logos at original resolution.

Differences vs. `image_to_design`: input is a **PDF URL or PDF file**, output is **one tree per requested page** (not a single tree), and the per-node fields tagged "PDF only" in the shared schema **are** populated here (vector paths, character-level styling, transform matrices, etc.).

## Sending the request

This endpoint supports two input modes:

1. **JSON URL mode**: send `application/json` with `pdf_url` and `page_no` when the PDF is already publicly reachable.
2. **Direct upload mode**: send `multipart/form-data` with a local PDF file in the `pdf_file` field and one or more `page_no` fields.

JSON example:

```bash
curl 'https://openapi.codia.ai/v2/open/pdf_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --data '{ "pdf_url": "https://example.com/file.pdf", "page_no": [0, 2, 5] }'
```

Direct upload example:

```bash
curl 'https://openapi.codia.ai/v2/open/pdf_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'pdf_file=@./file.pdf' \
  -F 'page_no=0' \
  -F 'page_no=2'
```

- **`pdf_url`** *(JSON mode, required)* — public URL of the PDF. Encrypted / password-protected PDFs are rejected.
- **`pdf_file`** *(upload mode, required, binary)* — the PDF itself. Stream the file directly; do not base64-encode it.
- **`page_no`** *(required)* — **0-indexed** page numbers. JSON mode uses an integer array; multipart mode repeats the `page_no` field once per page. Page count and file-size caps follow the global Codia API limits.

## Response shape

Standard Codia envelope; on success `data` carries:

| Field | What it is | How to use it |
|---|---|---|
| `data.configuration` | Same `Configuration` object as `image_to_design` — `baseWidth`, `measurementUnit` (`px` \| `pt`), `scalingFactor`. | Apply `scalingFactor` to every numeric value when rendering. `baseWidth` is the canvas width the trees were measured against (often page width in points or px, e.g. 1940). |
| `data.size` | Page dimensions in document units: `{ width, height }`. | Use to set up artboard / viewport per page. All pages in a single PDF share this size. |
| `data.pages[]` | One entry per requested page. Each entry is `{ visualElement: <Body root> }`. | Iterate pages in order; recurse into each `visualElement.childElements` to reach every region. |

## Walking a page tree

Each `data.pages[i].visualElement` is a `Body`-typed root with the same `VisualElement` shape used elsewhere in this API (see `image_to_design` for the full field guide). The headline pieces:

- **`elementType`** — `Body` at the root, then `Layer` / `Group` / `Text` / `Image` / `Vector` / `Component` inside. PDFs use `Vector` heavily for shapes, gradients, and logos.
- **`childElements`** — nested nodes; recurse depth-first.
- **`layoutConfig` / `styleConfig` / `processingMeta`** — same semantics as `image_to_design`.
- **`contentData`** — for `Text` reads `textValue`; for `Image` reads `imageSource` and/or the base64 in `imageData`; for `Vector` reads `vectorData` (see below).

### PDF-specific fields you can actually use

Fields the shared schema tags "PDF only" — these are real, populated, and useful on this endpoint:

- **`boundingBox`** *(`[x, y, width, height]`)* — exact node geometry in document coordinates. The most reliable positioning source for PDFs.
- **`displayOrder`** — z-order within the page; lower = drawn first.
- **`styleConfig.transformMatrix` / `extendedMatrix`** — affine transform applied to the node. `transformMatrix` is the 6-element PDF form `[a b c d e f]`; `extendedMatrix` is the CSS-compatible string. Apply this to handle rotated text, sheared images, etc.
- **`styleConfig.characterData`** — per-character styling keyed by character index. Use this when a single text node mixes fonts, sizes, or colors (very common in PDFs).
- **`styleConfig.cornerRadius`** — scalar fallback when the four-corner array isn't applicable.
- **`styleConfig.isRightToLeft`** — direction flag for Arabic / Hebrew text.
- **`contentData.vectorData`** — the actual vector path. Contains `pathItems[]` (each item is `{ pathType: "l" | "c", coordinates[] }` — `l` = line, `c` = cubic curve), plus `fillColor`, `strokeColor`, `strokeWidth`, `fillOpacity`, `strokeOpacity`, `lineCapStyle`, `lineJoinStyle`, `dashPattern`, `evenOddRule`, `isClosedPath`. Emit SVG `<path>` directly, or rebuild in your own renderer.
- **`contentData.imageData`** — base64-encoded image bytes for embedded raster images (alongside or instead of `imageSource`).
- **`contentData.svgTemplate`** — pre-rendered SVG markup template for compound vector content.
- **`contentData.maskingMode` / `blendingType`** — PDF graphics-state knobs (clip / soft-mask, blend mode). Map to CSS `mix-blend-mode` / SVG `<mask>` as appropriate.

### A minimal traversal

```ts
for (const page of response.data.pages) {
  console.log('page', page.visualElement.elementName, response.data.size);
  walk(page.visualElement);
}

function walk(node, depth = 0) {
  const pad = '  '.repeat(depth);
  if (node.elementType === 'Text') console.log(pad, 'TXT', node.contentData?.textValue);
  if (node.elementType === 'Image') console.log(pad, 'IMG', node.contentData?.imageSource);
  if (node.elementType === 'Vector') console.log(pad, 'VEC', node.contentData?.vectorData?.pathItems?.length, 'segs');
  node.childElements?.forEach(c => walk(c, depth + 1));
}
```

## Inputs, limits, billing

- **Input** — either JSON with `pdf_url` or `multipart/form-data` with `pdf_file`. Encrypted / password-protected PDFs are rejected.
- **Page selection** — `page_no` uses **0-based** indices. JSON mode sends an integer array; multipart mode repeats the `page_no` field once per page. Out-of-range indices are silently dropped from the response.
- **Billing** — consumes the unified Codia Open API balance (`GET /v2/open/credits`). 13 credits per processed page.
- **Latency** — synchronous. Throughput is per-page; a long document may take many seconds. For very long PDFs, batch the request by `page_no` ranges and parallelize.
- **Determinism** — same PDF + same `page_no` yields the same structural tree, but `elementId`s are regenerated each call; don't rely on cross-call ID stability.

## Errors

Uses the standard envelope with non-zero `code` and a descriptive `message`. HTTP status codes:
- `400` — bad input (missing `pdf_url` / `pdf_file`, malformed `page_no`, corrupt / encrypted PDF).
- `401` / `403` — missing / wrong / unauthorized API key.
- `402` — the subscription is inactive or credits are exhausted. See the global Errors section for recovery steps.
- `429` — rate-limited; back off and retry.
- `500` — internal error; safe to retry once.

### `measurementUnit`

`pdf_to_design` returns whichever unit the source PDF used. Most editorial / business PDFs report `pt` (PostScript points: 72 = 1 inch). PDFs exported from design tools at a specific pixel target may report `px`. Read this field per response and convert if your downstream renderer assumes one unit.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — fine for short PDFs. For documents with more than ~5 pages, prefer `POST /v2/open/tasks` with `operation=pdf_to_design` to avoid HTTP client timeouts, get webhook delivery, and support cancellation. Inputs and credit cost are identical to this v2 endpoint.

可选，由用户自定义的幂等键（最多 255 个字符）。设置后，成功（2xx）的响应会缓存 7 天。使用相同的键 + 相同的请求体重试，会返回缓存的响应（不额外扣除积分）；使用相同的键但不同的请求体重试，则返回 409。用于确保 POST 请求在网络故障时可以安全重试。对于 multipart/form-data 上传，请求会按表单字段和文件内容进行比较，因此即使客户端生成了新的 multipart boundary，重试的上传也会被重放。

Idempotency-Key

待处理 PDF 的公开 URL。必须可被 Codia 直接获取。

pdf_url

要处理的页码（从 0 开始），例如 [0, 2, 5]。

page_no

要处理的 PDF 文件，以 multipart 二进制部分发送。

pdf_file

每个要处理的页码（从 0 开始）各重复一次 multipart 的 page_no 字段。

转换成功。`data.pages` 是一个数组——每个已处理页面对应一项，每项包含一棵 `visualElement` 树，其 `VisualElement` 结构与 `image_to_design` 相同（另含操作描述中列出的 PDF 专属字段）。`data.size` 包含页面尺寸，`data.configuration` 包含画布缩放比例 / 单位。

code

message

configuration

pages

size

data

请求体格式错误或缺少必填参数

Idempotency-Key 已被用于不同的请求体。

请求频率超限。请等待 `Retry-After` 响应头中指定的秒数后再重试。

Vector

VELORA SKINCARE · SELL SHEET 2026

48 units

$49.00

MSRP

$17.50

WHOLESALE

24 months unopened

Shelf life

24 units · 3.1 kg

Case pack

Amber glass bottle, glass dropper

Packaging

15% vitamin C · hyaluronic acid · niacin

15% vitamin C · hyaluronic acid · niacinamide

Key actives

VLR-GS-030

Brightening vitamin C serum with hyaluro

Brightening vitamin C serum with hyaluronic acid. Fragrance-free,
vegan, dermatologist tested.

Glow Serum 30 ml

V E L O R A · W H O L E S A L E

Image

将 PDF 页面转换为可编辑的设计树，保留原始矢量、字体和颜色，而不是将其栅格化。

PDF 转设计

输入

输出

相关 API