The request body is malformed or missing required parameters

The request conflicts with an existing resource or idempotency key

Account does not have access to this endpoint

An unexpected error occurred on the server

Account balance is insufficient or subscription has expired

Rate limit exceeded for your subscription tier

Number of whole seconds to wait before retrying.

The API key is missing, invalid, or revoked

Envelope returned by GET/POST /v2/open/auto_recharge. `data` is the live auto-recharge configuration.

0 on success; non-zero mirrors HTTP status.

Hard cap on auto-recharge spend per calendar month.

Recharge fires when the live balance falls at or below this number.

Reusable component definition (when elementType is Component)

Global rendering settings for the design output

Envelope returned by GET /v2/open/credits. Carries the live balance plus monthly/topup split, current billing period bounds, and the user's auto-recharge configuration.

Live total available credit balance (monthly + topup). `-1` means unlimited (Enterprise).

End of the current billing period (RFC3339).

Start of the current billing period (RFC3339).

Recharge fires when `available_credits` falls at or below this.

Credits remaining in the current monthly allotment. `-1` for unlimited.

Wall-clock time when monthly credits reset. Equals `current_period_end`.

Credits remaining from one-time top-ups (never expire within the credit period).

Total credits granted in the current period (monthly + topups). `-1` for unlimited.

Credits consumed in the current billing period.

FIXED (exact size), FILL (stretch to parent), FIT_CONTENT (shrink to content)

Vision model that captions/describes the image. Defaults to `nano_banana_2`. All supported models currently cost 5 credits per request.

| Model | Best for | Credits |
| --- | --- | ---: |
| `nano_banana_2` | Fast, accurate captions for prompt extraction (Gemini 3.1 Flash). | 5 |
| `nano_banana_pro` | Long, detailed multi-aspect descriptions (Gemini 3 Pro). | 5 |
| `ideogram_v3` | Caption focused on style, composition, and typography. | 5 |

Background mode (model-dependent). For `gpt_image`: `transparent`, `opaque`, or `auto`.

Model that generates the image. Defaults to `nano_banana_2`. Supported models match Codia Studio for text-to-image generation. Credits are configured in `pricing.yaml` and returned by `GET /v2/open/limits`.

| Model | Best for |
| --- | --- |
| `nano_banana_2` | Fast everyday generation (Gemini 3.1 Flash). |
| `nano_banana_pro` | Studio-quality 4K visuals with advanced reasoning (Gemini 3 Pro). |
| `gpt_image` | Crisp in-image text, high-fidelity references, flexible sizes. Supports `quality` (`low`/`medium`/`high`/`auto`) and `background` (`transparent`/`opaque`/`auto`). |
| `seedream_5` | Photorealistic imagery with fine detail. Sizes are 1920-based, e.g. `1920x1080`. |
| `seedream_4_5` | Reliable photorealism, great for portraits. Sizes are 1920-based. |
| `recraft_v4` | Illustrations, icons, and vector-style art with precise style control. |
| `flux_2_pro` | High-quality FLUX generation by Black Forest Labs. |
| `flux_2_max` | Maximum-quality FLUX tier for premium results. |
| `ideogram_v3` | Excellent typography and creative compositions. |

Number of images to generate. Credits are charged per generated image.

Text description of the image to generate

Quality preset (model-dependent). For `gpt_image`: `low`, `medium`, `high`, or `auto`; omitted/`auto` uses the medium billing bucket.

Reference image URLs for style guidance (model-dependent)

Output image dimensions as `WIDTHxHEIGHT`. Common sizes: `1024x1024`, `1536x1024`, `1024x1536`

Public URL of the image to decompose into layers

Public URL of the mask image (white = area to erase, black = keep)

Model that performs the inpainting. Defaults to `codia_image_v2`. All supported models currently cost 13 credits per request.

| Model | Best for | Credits |
| --- | --- | ---: |
| `codia_image_v2` | Clean, fast inpainting for photos and UI. Best when the surrounding context is simple. | 13 |
| `nano_banana_2` | AI-aware erase that reconstructs complex context (Gemini 3.1 Flash). | 13 |
| `nano_banana_pro` | High-fidelity erase with intricate background reconstruction (Gemini 3 Pro). | 13 |

Public URL of the source image to reframe

Model that performs the reframe / outpaint. Defaults to `nano_banana_2`. Credits follow the `image_reframe` model/resolution table.

| Model | Default | 1K | 2K | 4K |
| --- | ---: | ---: | ---: | ---: |
| `gpt_image` | 8 | 8 | 34 | 34 |
| `nano_banana_2` | 18 | 18 | 27 | 40 |
| `nano_banana_pro` | 36 | 36 | 36 | 64 |
| `seedream_5` | 9 | 9 | 9 | 9 |
| `seedream_4_5` | 11 | 11 | 11 | 11 |
| `flux_2_pro` | 8 | 8 | 20 | - |
| `flux_2_max` | 19 | 19 | 43 | - |
| `ideogram_v3` | 16 | 16 | - | - |

Target resolution as `WIDTHxHEIGHT`. The image will be extended to fill this size.

Model that performs the remix. Defaults to `nano_banana_2`. Credits follow the `image_remix` model/resolution table.

| Model | Default | 1K | 2K | 4K |
| --- | ---: | ---: | ---: | ---: |
| `nano_banana_2` | 18 | 18 | 27 | 40 |
| `nano_banana_pro` | 36 | 36 | 36 | 64 |
| `gpt_image` | 8 | 8 | 34 | 34 |
| `seedream_5` | 9 | 9 | 9 | 9 |
| `seedream_4_5` | 11 | 11 | 11 | 11 |
| `recraft_v4` | 11 | 11 | 67 | - |
| `flux_2_pro` | 8 | 8 | 20 | - |
| `flux_2_max` | 19 | 19 | 43 | - |
| `ideogram_v3` | 16 | 16 | - | - |

Text description of the desired remix style

Output image dimensions as `WIDTHxHEIGHT`

Model that synthesises the new background. Defaults to `nano_banana_2`. All supported models currently cost 13 credits per request.

| Model | Best for | Credits |
| --- | --- | ---: |
| `nano_banana_2` | Fast background swaps (Gemini 3.1 Flash). Good default for most images. | 13 |
| `nano_banana_pro` | Studio-quality 4K backgrounds with realistic lighting and reflections. | 13 |
| `ideogram_v3` | Stylized, illustrative, or text-heavy backgrounds. | 13 |

Text description of the desired new background

Envelope returned by `POST /v2/open/image_to_design`. `code = 0` on success; `data` carries the hierarchical design tree (`visualElement`) plus the canvas-level rendering config (`configuration`). Walk `visualElement.childElements` recursively to reach every detected region — see the operation description for a field-by-field walkthrough.

0 on success; non-zero values mirror the HTTP status family (400/401/402/403/429/500).

Canvas-level rendering settings the tree was measured against. Apply `scalingFactor` to every numeric value when rendering.

Root of the design tree. Always `elementType: "Body"`. Its `childElements` form the rest of the page.

Human-readable status. `"ok"` on success, otherwise an error reason.

GPT Image only. Requests transparent or opaque background when supported. Ignored by non-GPT models.

Public URL of the source image to transform

Model that performs the image-to-image transformation. Defaults to `nano_banana_2`. Supported models match Codia Studio for image-to-image generation. Credits are configured in `pricing.yaml` and returned by `GET /v2/open/limits`.

| Model | Best for |
| --- | --- |
| `nano_banana_2` | Fast image-to-image edits guided by a text prompt (Gemini 3.1 Flash). |
| `nano_banana_pro` | Studio-quality 4K transformations with advanced reasoning (Gemini 3 Pro). |
| `gpt_image` | High-fidelity reference-driven edits with crisp text. Supports `quality` (`low`/`medium`/`high`/`auto`) and `background` (`transparent`/`opaque`/`auto`). |
| `seedream_5` | Photorealistic transformations with fine detail. Sizes are 1920-based. |
| `seedream_4_5` | Reliable photorealistic transformations. Sizes are 1920-based. |
| `recraft_v4` | Convert photos into illustrations, icons, or vector-style art. |
| `flux_2_pro` | High-quality FLUX-driven edits. |
| `flux_2_max` | Maximum-quality FLUX tier for premium edits. |
| `ideogram_v3` | Edits that retain or introduce strong typography. |

Text description of the desired transformation

GPT Image only. Controls OpenAI image quality for `model=gpt_image`. Omitted or `auto` uses the medium billing bucket. Ignored by non-GPT models.

Optional output dimensions as `WIDTHxHEIGHT`, e.g. `1024x1024`. For `gpt_image`, size contributes to the pricing key together with `quality`.

Model that performs the upscale. Defaults to `codia_image_v2`. Credits follow the `image_upscale` pricing table.

| Model | Default | 1K | 2K | 4K |
| --- | ---: | ---: | ---: | ---: |
| default / `codia_image_v2` | 16 | - | - | - |
| `ideogram_v3` | 16 | 16 | 16 | - |
| `nano_banana_2` | 18 | 18 | 27 | 40 |
| `nano_banana_pro` | 36 | 36 | 36 | 64 |
| `gpt_image` | 56 | 56 | 112 | - |

Public URL of the image with watermark to remove

Controls how an element is positioned within its parent

Operation-specific input. For pdf_to_ppt, pass either upload_id or a caller-hosted pdf_url.

Current account plan id, for example free, starter, pro, ultra, team, business, or enterprise.

Credits finally charged after cancellation. For pdf_to_ppt, this equals the number of pages already converted multiplied by the current per-page price.

Credits refunded by the cancel call. For pdf_to_ppt, this equals the number of pages not yet converted multiplied by the current per-page price.

Credits originally reserved or deducted for the task.

Optional HTTPS webhook URL called when the task reaches a terminal state.

Operation-specific input. URL-based image operations require image_url; image_object_erase also requires mask_url; prompt-based image operations require prompt; pdf_to_design requires pdf_url; pdf_to_ppt accepts either upload_id from /v2/open/uploads or a caller-hosted pdf_url. For PDF operations, omit page_no or send an empty array to process every page up to account limits.

Unix timestamp in seconds, present for terminal states.

Human-readable failure message, present when failed or canceled.

Machine-readable failure code, present when failed or canceled.

Operation-specific result. pdf_to_ppt success includes ppt_url; design operations return design DSL data.

Unix timestamp in seconds, present after processing starts.

Supported asynchronous Open API operations.

Get the latest state for one Open API task. The request must use the same API key that created the task. Terminal states are `succeeded`, `failed`, and `canceled`.

Unix seconds when the upload handle expires.

Opaque upload handle. This is not a public URL.

Metadata about how the element was detected

URL of the processed image with transparent background

Human-readable status or error description

Defines the visual appearance of an element

Per-character styling keyed by character index (PDF only)

CSS-format transformation matrix (PDF only)

Letter spacing in CSS px (relative to OCR-measured font-size). The Studio canvas converts this to a percentage of font-size at import time, matching Figma semantics.

6-element affine transformation matrix (PDF only)

Original file name (optional, used for record-keeping)

Public URL of the raster image to vectorize. Canonical field name (preferred over `pic_url`).

Public URL of the raster image to vectorize (PNG, JPG, GIF, WebP) (deprecated: use `image_url` instead).

Use this ID to poll for the conversion result

Record ID returned by /v2/open/svg_converter/create

Download URL for the generated SVG file. Present when status is complete.

Envelope returned by GET /v2/open/usage. Paginated, offset-based list of per-call usage records.

Whether more records exist after this page.

A node in the visual element tree describing a UI element, its position, style, and content.

Bounding box coordinates [x, y, width, height] (PDF only)

Rendering order within the page (PDF only)

Payload Codia POSTs to your `callback_url` when a task reaches a terminal state. See the Webhook callback section of `/v2/open/tasks`.

Human-readable error message when `status` is `failed`. Empty string on success.

Operation type, e.g. `pdf_to_ppt`, `image_to_design`.

Operation-specific result payload; same shape as GET /v2/open/tasks/{task_id} `result`. Empty / omitted on failure.

Task identifier returned by POST /v2/open/tasks.

Unix timestamp (seconds) when the event was emitted.

Backward-compatible alias for bearer API key authentication.

API key obtained from [Personal Center > API Keys](https://codia.ai/dashboard/developer). Your key works across all subscribed capabilities.

Codia Support

Codia API provides programmatic access to Codia visual intelligence capabilities. Convert UI screenshots into structured design tokens, extract layouts from PDF documents, generate editable PowerPoint files, vectorize images to SVG, and remove image backgrounds through simple REST endpoints.

## Getting Started

### 1. Buy Codia Open API

All public Open API endpoints share one Codia Open API balance. [**Buy or subscribe**](https://codia.ai/pricing/open_api/open_api_v2) to the unified API credits SKU once, then use the same credits across screenshot, PDF, image processing, PDF to PPT, and background removal APIs.

### 2. Generate an API Key

Go to [**Personal Center > API Keys**](https://codia.ai/dashboard/developer) and create a key. One key works across all Open API capabilities.

### 3. Install Codia Open API

Use Codia Open API to install these APIs into Codex, Claude, Cursor, and local agent workflows. Install the CLI with `npm install -g @codia/design-skills`, bind an API key with `codia-design auth set --api-key api_key_xxx`, install templates with `codia-design install --platform all`, then verify access with `codia-design credits`. See https://codia.ai/codia-design-skills and https://codia.ai/docs/codia-design-skills.

### 4. Monitor Credits and Usage

Use GET /v2/open/credits to check your remaining balance, GET /v2/open/usage to inspect call-level usage, GET/POST /v2/open/auto_recharge to manage automatic top-ups, and /v2/open/tasks to create, inspect, list, and cancel asynchronous work.

## Agent Workflows

For agent workflows, use Codia Open API to install Codia Open API tools into Codex, Claude, Cursor, and local agents.

## Figma SDK

For Figma plugin developers, see the [Figma SDK guide](https://codia.ai/docs/figma-sdk).

## Credit Matrix

Credits are charged from the unified Codia Open API balance. Model prices below come from `products.open_api.tools.*` in `pricing.yaml`; `GET /v2/open/limits` returns the live table.

### Fixed-price operations

| API / operation | Endpoint(s) | Credits |
| --- | --- | --- |
| Image to design | `POST /v2/open/image_to_design`, task `image_to_design` | 13 |
| PDF to design | `POST /v2/open/pdf_to_design`, task `pdf_to_design` | 13 / processed page |
| Remove background | `POST /v2/open/remove_bg`, task `remove_bg` | 13 |
| PDF to PPT | `POST /v2/open/pdf_to_ppt`, task `pdf_to_ppt` | 13 / converted page |
| PDF to PPT reconvert | `POST /v2/open/tasks/{task_id}/reconvert` | 13 / reconverted page |
| Replace background | `POST /v2/open/image/replace_background`, task `image_replace_background` | 13 |
| Object erase | `POST /v2/open/image/object_erase`, task `image_object_erase` | 13 |
| Describe image | `POST /v2/open/image/describe`, task `image_describe` | 5 |
| Watermark remove | `POST /v2/open/image/watermark_remove`, task `image_watermark_remove` | 13 |
| Layering | `POST /v2/open/image/layering`, task `image_layering` | 27 |
| SVG converter create | `POST /v2/open/svg_converter/create` | 13 |
| SVG converter result/limit | `GET /v2/open/svg_converter/result/{record_id}`, `GET /v2/open/svg_converter/limit` | 0 |
| Upload / estimate / task get-list-cancel | `/v2/open/uploads`, `/v2/open/estimate`, task status/list/cancel | 0 |

### Text-to-image and image-to-image

`image_generate` charges per generated image and multiplies by `n`. `image_to_image` charges per request. Both use the same model table.

| Model | Default | 1K | 2K | 4K |
| --- | ---: | ---: | ---: | ---: |
| `nano_banana_2` | 18 | 18 | 27 | 40 |
| `nano_banana_pro` | 36 | 36 | 36 | 64 |
| `seedream_5` | 9 | 9 | 9 | 9 |
| `seedream_4_5` | 11 | 11 | 11 | 11 |
| `recraft_v4` | 11 | 11 | 67 | - |
| `flux_2_pro` | 8 | 8 | 20 | - |
| `flux_2_max` | 19 | 19 | 43 | - |
| `ideogram_v3` | 16 | 16 | - | - |

GPT Image quality pricing for `image_generate` and `image_to_image`:

| Quality | 1K | 2K | 4K |
| --- | ---: | ---: | ---: |
| `low` | 2 | 9 | 9 |
| `medium` / omitted / `auto` | 8 | 34 | 34 |
| `high` | 33 | 133 | 133 |

### Remix

| Model | Default | 1K | 2K | 4K |
| --- | ---: | ---: | ---: | ---: |
| `nano_banana_2` | 18 | 18 | 27 | 40 |
| `nano_banana_pro` | 36 | 36 | 36 | 64 |
| `gpt_image` | 8 | 8 | 34 | 34 |
| `seedream_5` | 9 | 9 | 9 | 9 |
| `seedream_4_5` | 11 | 11 | 11 | 11 |
| `recraft_v4` | 11 | 11 | 67 | - |
| `flux_2_pro` | 8 | 8 | 20 | - |
| `flux_2_max` | 19 | 19 | 43 | - |
| `ideogram_v3` | 16 | 16 | - | - |

### Reframe

| Model | Default | 1K | 2K | 4K |
| --- | ---: | ---: | ---: | ---: |
| `gpt_image` | 8 | 8 | 34 | 34 |
| `nano_banana_2` | 18 | 18 | 27 | 40 |
| `nano_banana_pro` | 36 | 36 | 36 | 64 |
| `seedream_5` | 9 | 9 | 9 | 9 |
| `seedream_4_5` | 11 | 11 | 11 | 11 |
| `flux_2_pro` | 8 | 8 | 20 | - |
| `flux_2_max` | 19 | 19 | 43 | - |
| `ideogram_v3` | 16 | 16 | - | - |

### Upscale

| Model | Default | 1K | 2K | 4K |
| --- | ---: | ---: | ---: | ---: |
| default / `codia_image_v2` | 16 | - | - | - |
| `ideogram_v3` | 16 | 16 | 16 | - |
| `nano_banana_2` | 18 | 18 | 27 | 40 |
| `nano_banana_pro` | 36 | 36 | 36 | 64 |
| `gpt_image` | 56 | 56 | 112 | - |

For `image_generate`, one reference image is included. Extra references: `gpt_image`, `nano_banana_2`, and `nano_banana_pro` add 1 credit per extra reference; `recraft_v4` adds a flat 4 credits when extra references are present; `ideogram_v3` adds a flat 3 credits; Seedream and FLUX extra references are currently free.

## Errors

All endpoints use the same envelope: `{ code, message, data }`. On success `code = 0`. On failure `code` mirrors the HTTP status code (e.g. `code: 401` for a 401 response).

| HTTP status | When it happens |
| --- | --- |
| `400` | Invalid input — missing or malformed parameters, unsupported MIME, page index out of range, etc. |
| `401` | Missing, invalid, or expired API key. |
| `402` | Credit balance exhausted. Top up via the dashboard or `/v2/open/auto_recharge`. |
| `403` | API key not authorised for this endpoint or plan. |
| `404` | Resource (e.g. task) not found. |
| `409` | `Idempotency-Key` conflict — same key reused with a different payload. |
| `410` | Endpoint deprecated and removed. |
| `429` | Rate limited. Respect the `Retry-After` response header. |
| `500` | Internal error. Safe to retry once with backoff. |

The `message` field is a short human-readable description and is not part of any stable contract — do not parse it. Branch on `code` (or the HTTP status) and not on the message text.

## Rate limits

Limits apply per source IP and per API key. When you exceed a limit, the API returns `429 Too Many Requests`. `429` responses **always includes** a `Retry-After` header (in whole seconds) — when present, wait at least that long before retrying.

| Scope | Default limit |
| --- | --- |
| All Open API endpoints (per source IP) | 50 requests / second |
| Task status polling (`GET /v2/open/tasks/{task_id}`, per API key) | 60 requests / minute |
| Per-model image generation | Varies by model (see model catalog) |

If you're hitting limits for a legitimate workload, contact support — Enterprise plans can raise these caps.

## Pagination

This API uses two pagination styles, chosen per endpoint based on how data is most commonly consumed:

- **Offset-based** (`page` + `page_size`) — used by `GET /v2/open/usage` for billing/reporting UIs where users skip to arbitrary pages. The response includes `total` so you can render page numbers.
- **Cursor-based** (`limit` + `after`) — used by `GET /v2/open/tasks` for sequential consumption of new/changing data. The response includes `has_more`; pass the last item's `created_at` value as the next `after`. No `total` is returned (would be expensive on active task lists).

Do not mix the two styles in your client wrapper — keep separate iterators for each endpoint.

## Environments

There is no separate sandbox. Every request goes to the production base URL `https://api.codia.ai` — create a real API key and call it directly. Endpoints charge credits only on a successful response, so you can validate your integration with a small balance.

Codia API

**⚠️ Deprecated — legacy v1 endpoint.** This path is retained only for existing integrations. New integrations should use `POST /v2/open/image_to_design` (v2 unified Open API). Input, output, and billing are unchanged — this endpoint keeps its own independent legacy credit SKU.

---

**Cost**: 13 credits per successful call.

Turn a single UI screenshot into an editable, hierarchical design tree — the same representation Codia Studio uses internally and the foundation that downstream code-generation, Figma-import, and layer-decomposition workflows are built on.

## Request options

This endpoint supports two input modes:

1. **JSON URL mode**: send `application/json` with `image_url` when the image is already publicly reachable.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

JSON example:

```bash
curl 'https://api.codia.ai/v1/open/image_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --data '{ "image_url": "https://example.com/screenshot.png" }'
```

Direct upload example:

```bash
curl 'https://api.codia.ai/v1/open/image_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./screenshot.png'
```

## What this API is for

Given a public image URL of a UI (mobile screen, desktop page, dashboard, marketing hero — anything pixel-based), the service runs detection + layout reconstruction and returns a tree of **`VisualElement`** nodes that mirror how a designer would have built the screen in Figma or Sketch:

- Every visible region becomes a node with a position, a size, and a style.
- Container/child relationships are preserved (e.g. a card holds its title, body, and CTA).
- Layout intent (Flex vs. Absolute), text typography (font, size, weight, color), shapes, images, and effects are all reified into structured fields — not flattened into a single bitmap.

Typical use cases:
- **Image → code / image → Figma**: walk the tree and emit React / HTML / Figma nodes.
- **Design QA**: diff a screenshot against a spec by comparing structured trees.
- **Layer extraction**: feed the tree into downstream tools (e.g. our PDF/PPT pipeline or your own renderer).
- **Agent / LLM workflows**: give a model a structured layout instead of raw pixels so it can reason about "the price label sits inside the product card."

## How the response is shaped

The response uses the standard Codia envelope (`code`, `message`, `data`). On success `code = 0` and `data` contains two fields:

| Field | What it is | How to use it |
|---|---|---|
| `data.configuration` | Global rendering settings — `baseWidth`, `measurementUnit` (`px` \| `pt`), `scalingFactor`. | Multiply every numeric value in the tree by `scalingFactor` when rendering. Treat `baseWidth` as the canvas width the tree was measured against (375 for mobile, 1440 for desktop, etc.). |
| `data.visualElement` | The **root** of the visual tree. Always an `elementType: "Body"` node whose `childElements` recursively contain the rest of the page. | Traverse depth-first. The fields you care about per node depend on `elementType` (see below). |

## Walking the `VisualElement` tree

Each node has the same shape, but a handful of fields are populated based on `elementType`:

| `elementType` | Populated content fields | Typical meaning |
|---|---|---|
| `Body` | `layoutConfig`, `styleConfig` | Root of the page / artboard |
| `Layer` | `layoutConfig`, `styleConfig` | Generic container (card, section) |
| `Group` | `childElements` | Pure grouping, no own visuals |
| `Text` | `styleConfig.textConfig`, `contentData.textValue` | A run of text |
| `Image` | `contentData.imageSource` | Raster image (URL) |
| `Vector` | `contentData.vectorData` | Vector shape (mostly PDF; image_to_design uses `Image` / `Layer` for shapes) |
| `Component` | `componentSpec`, `contentData.componentReference` | Reusable detected component |

For every node:
- **`elementId` / `elementName`** — stable identifier + human label. Use `elementId` as your React `key` or Figma node id.
- **`childElements`** — array of nested `VisualElement`s. Empty leaf for text/image. Recurse here.
- **`processingMeta.detectionScore`** — confidence in `[0, 1]`. Filter or warn on low-confidence nodes when generating production code.
- **`processingMeta.surfaceArea`** — pixel area; useful for sorting or pruning tiny artifacts.

### `layoutConfig` — where the node sits

- `positionMode`:
  - `"Flex"` — the node participates in its parent's flex layout. Read `flexAttributes` (`flexDirection`, `alignItems`, `justifyContent`, `flexWrap`) on the **parent** to know how children flow.
  - `"Absolute"` — positioned at exact coordinates. Read `absoluteAttrs.coord` for the offset relative to the parent.
  - `"Normal"` / `"Relative"` — document-flow positioning (rare on this endpoint; common at the root).
- `flexibleMode` — present on containers, identifies the flex variant the detector chose.

In practice, the root `Body` is `Flex` and most children inherit Flex from their parent, so a naive emitter that maps `positionMode` → CSS `display: flex` + `position: absolute` will reproduce the layout faithfully.

### `styleConfig` — what the node looks like

This is the largest object in the response. Group the fields by what they describe:

- **Size** — `widthSpec`, `heightSpec`. Each is a `DimensionSpec` with `sizing` (`FIXED` = exact px, `FILL` = stretch to parent, `FIT_CONTENT` = shrink to children) and a numeric `value`. Map `FIXED → width: Npx`, `FILL → flex: 1` (or `width: 100%`), `FIT_CONTENT → width: auto`.
- **Text** (on `Text` nodes) — `textConfig.{fontSize, fontStyle, fontFamily, lineHeight, letterSpacing, textAlign}` + `textColor` (a `VisualColor` with `rgbValues` and `hexCode`). `letterSpacing` is in CSS px against the detected font-size; Studio converts to a percentage at import time (Figma semantics).
- **Border** — `borderConfig.{borderWidth, borderStyle, borderColor, borderRadius}`. `borderRadius` is an array `[tl, tr, br, bl]`; collapse to a single value if all four are equal.
- **Background** — `backgroundConfig` is a `oneOf` with three shapes discriminated by `type`:
  - `"COLOR"` → solid fill via `backgroundColor`.
  - `"IMAGE"` → `imageUrl` + CSS-style `backgroundSize` / `backgroundPosition`.
  - `"LINEAR_GRADIENT"` → `deg` + `gradientStops[]` (each stop = `{color, position}` where `position` is 0–1).
- **Effects / transforms** — `effectsList` (shadows, blurs), `opacityLevel` (0–255 — divide by 255 for CSS), `rotationAngle` (degrees), `paddingValues`, `overflowMode`.

Fields tagged "PDF only" in the schema (`characterData`, `transformMatrix`, `cornerRadius`, `isRightToLeft`, `extendedMatrix`) are not produced by image_to_design — they're shared with `pdf_to_design` and you can ignore them here. Same for `boundingBox`, `displayOrder`, and `contentData.{svgTemplate, imageData, maskingMode, blendingType}`.

### `contentData` — what the node displays

Only populated on leaf-ish nodes:
- `textValue` — the actual string for `Text` nodes.
- `imageSource` — public URL for `Image` nodes (re-hosted on Codia's CDN; safe to embed).
- `componentReference` / `componentAttributes` — pointer + props for detected components, paired with `componentSpec` on the same node.

## A minimal traversal

```ts
function walk(node: VisualElement, depth = 0) {
  console.log('  '.repeat(depth), node.elementType, node.elementId,
    node.elementType === 'Text' ? node.contentData?.textValue :
    node.elementType === 'Image' ? node.contentData?.imageSource : '');
  node.childElements?.forEach(child => walk(child, depth + 1));
}
walk(response.data.visualElement);
```

## Inputs, limits, billing

- **Input** — either JSON with a single `image_url` pointing to a publicly fetchable PNG / JPG / WebP, or `multipart/form-data` with an `image` file. For direct upload, Codia checks credits before reading and uploading the file. Field name `file` is also accepted for compatibility. Maximum side length and file-size limits follow the global Codia API limits.
- **Billing** — consumes the unified Codia Open API balance (see `GET /v2/open/credits`). 13 credits per successful call.
- **Latency** — synchronous; typical end-to-end is single-digit seconds for mobile screens, longer for dense desktop pages.
- **Idempotency** — same image URL produces the same tree modulo `elementId` regeneration; do not rely on stable IDs across calls.

## Errors

Uses the standard envelope with non-zero `code` and a descriptive `message`. HTTP status codes:
- `400` — bad input (missing/invalid `image_url`, unreachable URL, unsupported MIME).
- `401` / `403` — missing / wrong / unauthorized API key.
- `402` — credit balance exhausted (top up via the dashboard or `/v2/open/auto_recharge`).
- `429` — rate-limited; back off and retry.
- `500` — internal error; safe to retry once.

### `measurementUnit`

Always `px` for `image_to_design` — screen captures and rasterised UI are inherently pixel-based.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_to_design` instead. Inputs and credit cost are identical to this endpoint.

Successful conversion. `data.visualElement` is the root `Body` node of the tree — recurse through `childElements` to reach every detected region. `data.configuration` carries the canvas base width, unit, and a scale factor you should multiply every numeric value by before rendering. See the operation description above for a full walkthrough of `elementType`, `layoutConfig`, `styleConfig`, and `contentData`.

**⚠️ Deprecated — legacy v1 endpoint.** This path is retained only for existing integrations. New integrations should use `POST /v2/open/pdf_to_design` (v2 unified Open API). Input, output, and billing are unchanged — this endpoint keeps its own independent legacy credit SKU.

---

**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://api.codia.ai/v1/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://api.codia.ai/v1/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` — credits exhausted (see `/v2/open/auto_recharge`).
- `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 endpoint.

Successful conversion. `data.pages` is an array — one entry per processed page, each containing a `visualElement` tree with the same `VisualElement` shape as `image_to_design` (plus the PDF-only fields documented in the operation description). `data.size` carries the page dimensions and `data.configuration` carries the canvas scale / unit.

**⚠️ Deprecated — legacy v1 endpoint.** This path is retained only for existing integrations. New integrations should use `POST /v2/open/remove_bg` (v2 unified Open API). Input, output, and billing are unchanged — this endpoint keeps its own independent legacy credit SKU.

---

**Cost**: 13 credits per successful call.

Remove Background supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://api.codia.ai/v1/open/remove_bg' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./product.png'
```

Cut out the foreground subject of an image and return a PNG with a fully transparent background. A synchronous, single-purpose endpoint — no model parameter, no prompt, no options.

## What this API is for

Product photos for storefronts, profile avatars, sticker generation, compositing pipelines — any time you need the subject without its scene. Returns a true alpha-channel PNG (not a flat white background).

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the image to process. PNG, JPG, or WebP. Must be reachable from Codia's network. |

## Response

Standard envelope. Unique to this endpoint (not the shared `ImageUrlListSuccess`): `data.image_url` is a **single** string — a CDN URL to the processed transparent PNG. Download promptly; the URL is pre-signed.

```json
{ "code": 0, "message": "ok", "data": { "image_url": "https://cdn.codia.ai/bg-removed/abc.png" } }
```

## Billing & limits

- 13 credits per successful call, from the unified Codia Open API balance.
- Synchronous; typically completes within a few seconds.
- Output is always PNG with an alpha channel, at the input image's resolution.

## Errors

Standard set — `400` for bad input, `401`/`403` auth, `402` credits, `429` rate limit, `500` internal.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=remove_bg` instead. Inputs and credit cost are identical to this endpoint.

**Cost**: Free — account query.

Read the current auto-recharge configuration for the authenticated account. Auto-recharge keeps long-running pipelines from breaking on `402` by topping up credits automatically when the balance drops below a threshold.

## Response shape

Standard envelope. `data` carries:

| Field | Meaning |
|---|---|
| `enabled` | Whether auto-recharge is currently on. |
| `threshold_credits` | When the balance falls **at or below** this number, a recharge fires. |
| `recharge_credits` | How many credits each recharge adds. One of `100`, `200`, `500`. |
| `monthly_max_recharge_credits` | Safety cap on total auto-recharge spend per calendar month. Once exhausted, recharges pause until the next month. |

If auto-recharge has never been configured, `enabled` is `false` and the numeric fields may be missing or zero.

## Errors

- `401` — auth issue.
- `500` — internal error.

**Cost**: Free — settings update (does not include the recharge itself).

Update the auto-recharge configuration. Send only the fields you want to change — omitted fields keep their current values.

## Body fields

| Field | Type | Notes |
|---|---|---|
| `enabled` | boolean | Master switch. Set `false` to disable auto-recharge entirely (other fields keep their values but are inert). |
| `threshold_credits` | integer | Auto-recharge fires when the live balance falls at or below this number. |
| `recharge_credits` | integer | How many credits to add per recharge. Must be one of `100`, `200`, `500`. |
| `monthly_max_recharge_credits` | integer | Hard cap on auto-recharge spend per calendar month — once exhausted, further auto-recharges pause until the month rolls over. Set this to bound your worst-case bill. |

A recharge bills the payment method on file at the moment it fires; make sure the account has a valid card and budget for it.

## Response

Standard envelope. `data` mirrors the updated settings (same shape as the GET response).

## Errors

- `400` — invalid combination (e.g. `recharge_credits` not in the allowed enum).
- `401` — auth issue.
- `402` — no valid payment method on file.
- `500` — internal error.

**Cost**: Free — account query.

Read the **live** Codia Open API balance for the authenticated account. The balance is shared across every Open API endpoint (image_to_design, pdf_to_*, svg_converter, image/*, etc.) — there is no per-capability quota.

Call this before submitting expensive jobs (e.g. PDF-to-PPT, multi-image generation) to fail fast on insufficient funds rather than getting a `402` mid-flow. Pair with `/v2/open/auto_recharge` if you want to top up automatically.

## Response shape

Standard envelope. `data.credits` is an integer — current balance in credits. There is no fractional unit.

## Errors

- `401` — missing / invalid API key.
- `500` — internal error; retry safe.

Estimate task credits before creating a task. For `pdf_to_ppt`, pass either `input.upload_id` from `/v2/open/uploads` or a caller-hosted `input.pdf_url`. Estimation does not create a task and does not deduct credits.

**Cost**: 5 credits per successful call.

Image Describe supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://api.codia.ai/v2/open/image/describe' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./image.png'
```

Get a natural-language description of what's in an image — the only non-image-output endpoint in the Image Processing family. Synchronous.

## What this API is for

Auto-captioning for accessibility / SEO, classification or moderation pre-screening, building alt-text at scale, feeding image context into a downstream text-only LLM. Output is a single English sentence-or-paragraph describing subject, scene, and notable details — **not** a structured tagging output. For structured layout extraction, use `image_to_design` instead.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the image to describe. |
| `model` | no | Model ID. Defaults to `nano_banana_2`. Also: `nano_banana_pro` (more detailed), `ideogram_v3`. |

## Response

Unique to this endpoint (not `ImageUrlListSuccess`): `data.description` is a single string.

```json
{ "code": 0, "message": "ok", "data": { "description": "A red ceramic mug on a wooden desk beside an open notebook…" } }
```

## Billing & limits

- **5 credits per request** (higher than most image endpoints — vision-language model cost).
- Synchronous.

## Errors

Standard set.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_describe` instead. Inputs and credit cost are identical.

Optional user-supplied key (up to 255 chars). When set, a successful (2xx) response is cached for 7 days. A retry with the same key + identical request body returns the cached response (no extra credit charged); a retry with the same key but a different body returns 409. Use to make POST safe to retry on network failures.

Idempotency-Key

Idempotency-Key reused with a different request body.

**Cost**: configured per generated image in `pricing.yaml` (multiplied by `n`).

Text-to-image generation. Produce one or more images from a natural-language prompt, optionally steered by reference images for style or composition. Synchronous; routes through whichever model you pick.

## What this API is for

The canonical "generate image from text" endpoint. Use it for hero art, marketing assets, agent-driven illustration, batched A/B variants. Reference images give you style/subject control without fine-tuning.

## Request

| Field | Required | Notes |
|---|---|---|
| `prompt` | yes | Text description of the image to generate. The most important field — be specific about subject, composition, lighting, and style. |
| `n` | no | Number of images to generate. Default `1`. **Credits are charged per generated image**, not per call. |
| `size` | no | Output dimensions as `WIDTHxHEIGHT`, e.g. `1024x1024`. Defaults vary by model. Common: `1024x1024`, `1536x1024`, `1024x1536`. |
| `model` | no | Model ID. Default `nano_banana_2`. Available: `nano_banana_2`, `nano_banana_pro`, `gpt_image`, `seedream_5`, `seedream_4_5`, `recraft_v4`, `flux_2_pro`, `flux_2_max`, `ideogram_v3`. Each has its own aesthetic / strength — see the table below. |
| `quality` | no | Quality preset (model-dependent). For `gpt_image`: `low` / `medium` / `high` / `auto`. Omitted/`auto` bills as the medium bucket. Ignored by other models. |
| `background` | no | Background mode (model-dependent). For `gpt_image`: `transparent` / `opaque` / `auto`. |
| `reference_images` | no | Array of public image URLs to steer the generation. Most models accept up to a handful — semantics vary (style ref vs. subject ref). |

### Model cheat-sheet

| Model | Strength |
|---|---|
| `nano_banana_2` (default) | Fast, general-purpose, good prompt adherence. |
| `nano_banana_pro` | Higher fidelity at higher latency. |
| `seedream_5` / `seedream_4_5` | Cinematic, photographic. |
| `flux_2_pro` / `flux_2_max` | High-quality, very precise prompt following. |
| `gpt_image` | Best for text inside images and structured layouts. Supports `quality` and `background`. |
| `recraft_v4` | Vector-friendly art / illustration. |
| `ideogram_v3` | Strong typography, posters, logos. |

## Response

Shared `ImageUrlListSuccess` — `data.image_urls` is an array of CDN URLs, length `n`.

## Billing

**Credits charged per generated image**, not per call. For `n = 4`, the configured per-image model price is multiplied by 4. Check `GET /v2/open/limits` for the live per-operation price table and `GET /v2/open/usage` for charged calls. Uses the unified Codia Open API balance.

## Errors

- `400` — missing/empty `prompt`, invalid `size` format, unknown `model`, too many `reference_images`.
- `401` / `403` — auth.
- `402` — credits exhausted.
- `429` — rate limit.
- `500` — internal; safe to retry.

> **Sync vs. async**
> This synchronous endpoint returns the result inline. When `n > 1` the call generates images sequentially and may approach HTTP timeouts; prefer `POST /v2/open/tasks` with `operation=image_generate` for batch jobs (and for webhook delivery / retry semantics). Inputs and per-image credit cost are identical.

**Cost**: configured in `pricing.yaml` (model-dependent — see `model` field).

Image to Image supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://api.codia.ai/v2/open/image/image_to_image' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./image.png' \
  -F 'prompt=make it watercolor'
```

Transform a source image into a new one steered by a text prompt — "this photo, but Studio Ghibli style", "this product shot, but at sunset", "this sketch, refined into a finished painting". Synchronous. Different from `remix` (which preserves more structure) and `replace_background` (which only changes the background).

## What this API is for

Style transfer, refinement, restylization, scene editing — any task framed as "take this image and change it according to this instruction". Holds onto the source's overall composition more loosely than `remix` — use that one when you need tighter structural preservation.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the source image. |
| `prompt` | yes | Text description of the desired transformation. |
| `model` | no | Default `nano_banana_2`. Same model menu as `generate_image`: `nano_banana_2`, `nano_banana_pro`, `gpt_image`, `seedream_5`, `seedream_4_5`, `recraft_v4`, `flux_2_pro`, `flux_2_max`, `ideogram_v3`. |
| `size` | no | Output dimensions as `WIDTHxHEIGHT`. For `gpt_image`, size is normalized into the pricing resolution bucket (`1K`, `2K`, `4K`). |
| `quality` | no | GPT Image only: `low`, `medium`, `high`, or `auto`. Omitted/`auto` bills as the medium bucket. Ignored by non-GPT models. |
| `background` | no | GPT Image only: `transparent`, `opaque`, or `auto`. Ignored by non-GPT models. |

## Response

Shared `ImageUrlListSuccess` — `data.image_urls` carries one URL of the transformed image.

## Billing & limits

- Credits come from `pricing.yaml` for the selected model. For `gpt_image`, the billing key combines resolution and quality, e.g. `1K_high`; call `GET /v2/open/limits` for live values.
- Synchronous, single-call.

## When to pick what

- Want a complete transformation? → `image_to_image`.
- Want to keep structure but change style? → `remix`.
- Want to keep subject and only change scene? → `replace_background`.
- Want to start from scratch with optional refs? → `generate_image`.

## Errors

Standard set.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_to_image` instead. Inputs and credit cost are identical.

**Cost**: 27 credits per successful call.

Image Layering supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://api.codia.ai/v2/open/image/layering' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./image.png'
```

Decompose a single image into an **ordered stack of editable layers** — background, subject(s), and overlays — each rendered separately. The output is a JSON DSL describing the layer tree plus the per-layer image data. Use this when you want a designer-style PSD-equivalent, not a single flat composition.

## What this API is for

Turning a flat marketing image back into editable components; pre-processing for downstream compositing; setting up animated reveals where each layer animates separately; segmenting photo content for fine-grained editing.

Different from `image_to_design`: that one returns a structural design-tree (Body / Layer / Text / Image nodes with positions and styles). `image_layering` returns visual layers (independent rendered images that you can stack). They complement each other.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the image to decompose. |

No `model` parameter — uses Codia's layering pipeline.

## Response

Unique to this endpoint:

| Field | Type | Meaning |
|---|---|---|
| `data.type` | integer | Result-type code. Identifies the schema variant of `dsl`. |
| `data.dsl` | string | **JSON-encoded** layer tree. Parse client-side. Contains layer metadata + URLs to the rendered layer images. |

```json
{ "code": 0, "message": "ok", "data": { "type": 1, "dsl": "{\"layers\":[…]}" } }
```

The `dsl` field is intentionally a string (not a nested object) so you can store it verbatim or stream it without re-encoding.

## Billing & limits

- 27 credits per request from the unified Codia Open API balance.
- Synchronous.

## Errors

Standard set.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_layering` instead. Inputs and credit cost are identical.

**Cost**: 13 credits per successful call.

Image Object Erase supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://api.codia.ai/v2/open/image/object_erase' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./photo.png' \
  -F 'mask=@./mask.png'
```

Remove specific regions of an image as identified by a **mask** image, and inpaint the gap so the result looks like the object was never there. Synchronous.

## What this API is for

Deleting people from background plates, removing unwanted objects from product shots, cleaning up screenshots before redistribution. Unlike `watermark_remove` (which auto-detects), this endpoint requires you to **specify exactly what to erase** via a binary mask.

## Mask format

`mask_url` must point to an image with the **same dimensions** as `image_url`:

- **White (255)** pixels = area to erase + inpaint.
- **Black (0)** pixels = keep as-is.
- Grayscale values in between produce partial blending; for crisp removal, threshold your mask to pure black/white.

The mask can be a separate PNG you generated client-side (e.g. from a brush UI or a segmentation model) or an alpha-channel cutout. Soft edges in the mask produce softer transitions in the result.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the source image. |
| `mask_url` | yes | Public URL of the mask image (same dimensions as source). |
| `model` | no | Model ID. Defaults to `codia_image_v2`. Also: `nano_banana_2`, `nano_banana_pro` (higher fidelity at higher latency). |

## Response

Shared `ImageUrlListSuccess` — `data.image_urls` carries one CDN URL of the cleaned image.

## Billing & limits

- 13 credits per request from the unified Codia Open API balance.
- Synchronous.

## Errors

Standard set; in particular `400` on size mismatch between image and mask.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_object_erase` instead. Inputs and credit cost are identical.

**Cost**: Model-priced per successful call. See the Credit Matrix for `image_reframe` model and resolution prices.

Image Reframe supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://api.codia.ai/v2/open/image/reframe' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./image.png' \
  -F 'resolution=1024x1024'
```

Outpaint / extend an image to fill a larger canvas at a specified target resolution — generate new pixels on the outside of the original frame rather than scaling it up. Synchronous.

## What this API is for

Converting square assets to wide banner formats, extending portraits into landscape, repurposing a 1:1 product photo as a 16:9 hero image. Different from `upscale` (which adds pixels *inside* the same crop) — `reframe` adds pixels *outside* it.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the source. |
| `resolution` | yes | Target dimensions as `WIDTHxHEIGHT`, e.g. `1920x1080`. The output image will be exactly this size, with the source placed inside and new content generated to fill the rest. |
| `model` | no | Default `nano_banana_2`. Also: `nano_banana_pro`, `ideogram_v3`. |

If `resolution` matches the source's aspect ratio, the result is effectively an upscale (use `upscale` instead). The endpoint shines when the **aspect ratio changes** and net new pixels need to be hallucinated.

## Response

Shared `ImageUrlListSuccess` — one URL.

## Billing & limits

- Credits follow the `image_reframe` model/resolution table in the global Credit Matrix.
- Synchronous.

## Errors

Standard set; `400` on malformed `resolution`.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_reframe` instead. Inputs and credit cost are identical.

**Cost**: Model-priced per successful call. See the Credit Matrix for `image_remix` model and resolution prices.

Image Remix supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://api.codia.ai/v2/open/image/remix' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./image.png' \
  -F 'prompt=turn into pixel art' \
  -F 'size=1024x1024'
```

Generate a new image that **preserves the structure** of a source (composition, layout, pose, key shapes) while changing the rest according to a prompt. Stronger structural preservation than `image_to_image` — use this when the silhouette / framing matters and only the surface should change.

## What this API is for

Thumbnail variants that keep the same crop; alternate color schemes for the same composition; style variants for marketing across regions; iterating on a moodboard image.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the source. |
| `prompt` | yes | Description of the desired remix. |
| `model` | no | Default `nano_banana_2`. Also: `nano_banana_pro`, `ideogram_v3`. |
| `size` | no | Output dimensions as `WIDTHxHEIGHT`. If omitted, output matches the source's aspect. |

## Response

Shared `ImageUrlListSuccess` — one URL in `data.image_urls`.

## Billing & limits

- Credits follow the `image_remix` model/resolution table in the global Credit Matrix.
- Synchronous.

## Errors

Standard set.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_remix` instead. Inputs and credit cost are identical.

**Cost**: 13 credits per successful call.

Image Replace Background supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://api.codia.ai/v2/open/image/replace_background' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./product.png' \
  -F 'prompt=clean white studio background'
```

Keep the foreground subject of an image and synthesize a new background described by a text prompt. Synchronous, single-call. Combines background removal + inpainting + generative rendering in one step.

## What this API is for

Reshooting product photography against new scenes ("on a marble counter", "in front of a sunset window"), reusing portraits across campaigns, or any time you want to keep the subject and change its environment. The subject is preserved; the prompt only steers the new background.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the source image. |
| `prompt` | yes | Natural-language description of the desired new background. Be specific about lighting, surface, and context for best results. |
| `model` | no | Model ID. Defaults to `nano_banana_2`. Also: `nano_banana_pro` (higher fidelity), `ideogram_v3` (alternative aesthetic). |

**Prompt tips**: describe the surface or scene ("clean white marble table"), the lighting ("soft studio lighting from the left"), and the mood. Avoid contradicting the subject's lighting unless you want the subject re-lit (the model may match it).

## Response

Shared `ImageUrlListSuccess` shape — `data.image_urls` is an array of CDN URLs (length 1).

## Billing & limits

- 13 credits per request from the unified Codia Open API balance.
- Synchronous, single-digit-second latency for typical inputs.

## Errors

Standard set — `400` bad input (missing `image_url` or `prompt`), `401`/`403` auth, `402` credits, `429` rate limit, `500` internal.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_replace_background` instead. Inputs and credit cost are identical.

**Cost**: Model-priced per successful call. See the Credit Matrix for `image_upscale` model and resolution prices.

Image Upscale supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://api.codia.ai/v2/open/image/upscale' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./image.png'
```

Enlarge an image to a higher resolution while reconstructing detail (not just bilinear interpolation). Model-driven — different models trade off sharpness, smoothness, and processing time. Synchronous.

## What this API is for

Recovering print-quality assets from low-resolution sources, preparing low-res user uploads for downstream tasks (e.g. background removal that needs more pixels), or salvaging legacy thumbnails. Use it before any pipeline step that benefits from more pixels — don't chain it after a generative step (those models already output at their target resolution).

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the image to upscale. |
| `model` | no | Model ID. Defaults to `codia_image_v2` (fast, balanced). Also available: `ideogram_v3` (sharper edges, slower). |

Upscale factor is determined by the model, not a request parameter — typically 2× to 4×. Resulting dimensions are returned implicitly via the output URL.

## Response

Shared `ImageUrlListSuccess` shape — `data.image_urls` is an array of CDN URLs (length 1 for this endpoint). Use the first entry.

```json
{ "code": 0, "message": "ok", "data": { "image_urls": ["https://cdn.codia.ai/upscale/xyz.png"] } }
```

## Billing & limits

- Credits follow the `image_upscale` model/resolution table in the global Credit Matrix.
- Synchronous. Latency scales with input size; very large inputs may approach minute-scale.

## Errors

Standard set — `400` bad input, `401`/`403` auth, `402` credits, `429` rate limit, `500` internal.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_upscale` instead. Inputs and credit cost are identical.

**Cost**: 13 credits per successful call.

Image Watermark Remove supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://api.codia.ai/v2/open/image/watermark_remove' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./image.png'
```

Detect and remove visible watermarks from an image — text overlays, logos, repeated patterns, corner stamps. Auto-detection (no mask required). Synchronous.

> ⚠️ **Use responsibly.** Only call this endpoint on images you own or have explicit permission to edit. Removing watermarks from third-party content may violate copyright or terms of service.

## What this API is for

Recovering pre-watermarked archive footage, removing automatic camera stamps from your own captures, cleaning up assets where you hold the rights but only have the watermarked export. Not for laundering stock photography or competitor content.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the watermarked image. |

No `model` parameter — detection is automatic.

## Response

Shared `ImageUrlListSuccess` — `data.image_urls` carries one URL of the cleaned image. If no watermark is detected, the original image (or a near-identity copy) is returned.

## Billing & limits

- 13 credits per request from the unified Codia Open API balance.
- Synchronous.

## Errors

Standard set.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_watermark_remove` instead. Inputs and credit cost are identical.

**Cost**: 13 credits per successful call.

Turn a single UI screenshot into an editable, hierarchical design tree — the same representation Codia Studio uses internally and the foundation that downstream code-generation, Figma-import, and layer-decomposition workflows are built on.

## Request options

This endpoint supports two input modes:

1. **JSON URL mode**: send `application/json` with `image_url` when the image is already publicly reachable.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

JSON example:

```bash
curl 'https://api.codia.ai/v2/open/image_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --data '{ "image_url": "https://example.com/screenshot.png" }'
```

Direct upload example:

```bash
curl 'https://api.codia.ai/v2/open/image_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./screenshot.png'
```

## What this API is for

Given a public image URL of a UI (mobile screen, desktop page, dashboard, marketing hero — anything pixel-based), the service runs detection + layout reconstruction and returns a tree of **`VisualElement`** nodes that mirror how a designer would have built the screen in Figma or Sketch:

- Every visible region becomes a node with a position, a size, and a style.
- Container/child relationships are preserved (e.g. a card holds its title, body, and CTA).
- Layout intent (Flex vs. Absolute), text typography (font, size, weight, color), shapes, images, and effects are all reified into structured fields — not flattened into a single bitmap.

Typical use cases:
- **Image → code / image → Figma**: walk the tree and emit React / HTML / Figma nodes.
- **Design QA**: diff a screenshot against a spec by comparing structured trees.
- **Layer extraction**: feed the tree into downstream tools (e.g. our PDF/PPT pipeline or your own renderer).
- **Agent / LLM workflows**: give a model a structured layout instead of raw pixels so it can reason about "the price label sits inside the product card."

## How the response is shaped

The response uses the standard Codia envelope (`code`, `message`, `data`). On success `code = 0` and `data` contains two fields:

| Field | What it is | How to use it |
|---|---|---|
| `data.configuration` | Global rendering settings — `baseWidth`, `measurementUnit` (`px` \| `pt`), `scalingFactor`. | Multiply every numeric value in the tree by `scalingFactor` when rendering. Treat `baseWidth` as the canvas width the tree was measured against (375 for mobile, 1440 for desktop, etc.). |
| `data.visualElement` | The **root** of the visual tree. Always an `elementType: "Body"` node whose `childElements` recursively contain the rest of the page. | Traverse depth-first. The fields you care about per node depend on `elementType` (see below). |

## Walking the `VisualElement` tree

Each node has the same shape, but a handful of fields are populated based on `elementType`:

| `elementType` | Populated content fields | Typical meaning |
|---|---|---|
| `Body` | `layoutConfig`, `styleConfig` | Root of the page / artboard |
| `Layer` | `layoutConfig`, `styleConfig` | Generic container (card, section) |
| `Group` | `childElements` | Pure grouping, no own visuals |
| `Text` | `styleConfig.textConfig`, `contentData.textValue` | A run of text |
| `Image` | `contentData.imageSource` | Raster image (URL) |
| `Vector` | `contentData.vectorData` | Vector shape (mostly PDF; image_to_design uses `Image` / `Layer` for shapes) |
| `Component` | `componentSpec`, `contentData.componentReference` | Reusable detected component |

For every node:
- **`elementId` / `elementName`** — stable identifier + human label. Use `elementId` as your React `key` or Figma node id.
- **`childElements`** — array of nested `VisualElement`s. Empty leaf for text/image. Recurse here.
- **`processingMeta.detectionScore`** — confidence in `[0, 1]`. Filter or warn on low-confidence nodes when generating production code.
- **`processingMeta.surfaceArea`** — pixel area; useful for sorting or pruning tiny artifacts.

### `layoutConfig` — where the node sits

- `positionMode`:
  - `"Flex"` — the node participates in its parent's flex layout. Read `flexAttributes` (`flexDirection`, `alignItems`, `justifyContent`, `flexWrap`) on the **parent** to know how children flow.
  - `"Absolute"` — positioned at exact coordinates. Read `absoluteAttrs.coord` for the offset relative to the parent.
  - `"Normal"` / `"Relative"` — document-flow positioning (rare on this endpoint; common at the root).
- `flexibleMode` — present on containers, identifies the flex variant the detector chose.

In practice, the root `Body` is `Flex` and most children inherit Flex from their parent, so a naive emitter that maps `positionMode` → CSS `display: flex` + `position: absolute` will reproduce the layout faithfully.

### `styleConfig` — what the node looks like

This is the largest object in the response. Group the fields by what they describe:

- **Size** — `widthSpec`, `heightSpec`. Each is a `DimensionSpec` with `sizing` (`FIXED` = exact px, `FILL` = stretch to parent, `FIT_CONTENT` = shrink to children) and a numeric `value`. Map `FIXED → width: Npx`, `FILL → flex: 1` (or `width: 100%`), `FIT_CONTENT → width: auto`.
- **Text** (on `Text` nodes) — `textConfig.{fontSize, fontStyle, fontFamily, lineHeight, letterSpacing, textAlign}` + `textColor` (a `VisualColor` with `rgbValues` and `hexCode`). `letterSpacing` is in CSS px against the detected font-size; Studio converts to a percentage at import time (Figma semantics).
- **Border** — `borderConfig.{borderWidth, borderStyle, borderColor, borderRadius}`. `borderRadius` is an array `[tl, tr, br, bl]`; collapse to a single value if all four are equal.
- **Background** — `backgroundConfig` is a `oneOf` with three shapes discriminated by `type`:
  - `"COLOR"` → solid fill via `backgroundColor`.
  - `"IMAGE"` → `imageUrl` + CSS-style `backgroundSize` / `backgroundPosition`.
  - `"LINEAR_GRADIENT"` → `deg` + `gradientStops[]` (each stop = `{color, position}` where `position` is 0–1).
- **Effects / transforms** — `effectsList` (shadows, blurs), `opacityLevel` (0–255 — divide by 255 for CSS), `rotationAngle` (degrees), `paddingValues`, `overflowMode`.

Fields tagged "PDF only" in the schema (`characterData`, `transformMatrix`, `cornerRadius`, `isRightToLeft`, `extendedMatrix`) are not produced by image_to_design — they're shared with `pdf_to_design` and you can ignore them here. Same for `boundingBox`, `displayOrder`, and `contentData.{svgTemplate, imageData, maskingMode, blendingType}`.

### `contentData` — what the node displays

Only populated on leaf-ish nodes:
- `textValue` — the actual string for `Text` nodes.
- `imageSource` — public URL for `Image` nodes (re-hosted on Codia's CDN; safe to embed).
- `componentReference` / `componentAttributes` — pointer + props for detected components, paired with `componentSpec` on the same node.

## A minimal traversal

```ts
function walk(node: VisualElement, depth = 0) {
  console.log('  '.repeat(depth), node.elementType, node.elementId,
    node.elementType === 'Text' ? node.contentData?.textValue :
    node.elementType === 'Image' ? node.contentData?.imageSource : '');
  node.childElements?.forEach(child => walk(child, depth + 1));
}
walk(response.data.visualElement);
```

## Inputs, limits, billing

- **Input** — either JSON with a single `image_url` pointing to a publicly fetchable PNG / JPG / WebP, or `multipart/form-data` with an `image` file. For direct upload, Codia checks credits before reading and uploading the file. Field name `file` is also accepted for compatibility. Maximum side length and file-size limits follow the global Codia API limits.
- **Billing** — consumes the unified Codia Open API balance (see `GET /v2/open/credits`). 13 credits per successful call.
- **Latency** — synchronous; typical end-to-end is single-digit seconds for mobile screens, longer for dense desktop pages.
- **Idempotency** — same image URL produces the same tree modulo `elementId` regeneration; do not rely on stable IDs across calls.

## Errors

Uses the standard envelope with non-zero `code` and a descriptive `message`. HTTP status codes:
- `400` — bad input (missing/invalid `image_url`, unreachable URL, unsupported MIME).
- `401` / `403` — missing / wrong / unauthorized API key.
- `402` — credit balance exhausted (top up via the dashboard or `/v2/open/auto_recharge`).
- `429` — rate-limited; back off and retry.
- `500` — internal error; safe to retry once.

### `measurementUnit`

Always `px` for `image_to_design` — screen captures and rasterised UI are inherently pixel-based.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_to_design` instead. Inputs and credit cost are identical to this v2 endpoint.

Returns the live Open API limits for the authenticated API key, including image caps, PDF caps, async task queue/concurrency limits, rate limits, and per-operation credit costs. This endpoint is free and does not consume credits.

**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://api.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://api.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` — credits exhausted (see `/v2/open/auto_recharge`).
- `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.

Compatibility alias for creating a `pdf_to_ppt` task. Prefer `POST /v2/open/tasks` with `operation: "pdf_to_ppt"` for new integrations. **Cost** comes from `products.open_api.tools.pdf_to_ppt` in `pricing.yaml` multiplied by processed page count.

**Cost**: 13 credits per successful call.

Remove Background supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://api.codia.ai/v2/open/remove_bg' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./product.png'
```

Cut out the foreground subject of an image and return a PNG with a fully transparent background. A synchronous, single-purpose endpoint — no model parameter, no prompt, no options.

## What this API is for

Product photos for storefronts, profile avatars, sticker generation, compositing pipelines — any time you need the subject without its scene. Returns a true alpha-channel PNG (not a flat white background).

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the image to process. PNG, JPG, or WebP. Must be reachable from Codia's network. |

## Response

Standard envelope. Unique to this endpoint (not the shared `ImageUrlListSuccess`): `data.image_url` is a **single** string — a CDN URL to the processed transparent PNG. Download promptly; the URL is pre-signed.

```json
{ "code": 0, "message": "ok", "data": { "image_url": "https://cdn.codia.ai/bg-removed/abc.png" } }
```

## Billing & limits

- 13 credits per successful call, from the unified Codia Open API balance.
- Synchronous; typically completes within a few seconds.
- Output is always PNG with an alpha channel, at the input image's resolution.

## Errors

Standard set — `400` for bad input, `401`/`403` auth, `402` credits, `429` rate limit, `500` internal.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=remove_bg` instead. Inputs and credit cost are identical to this v2 endpoint.

**Cost**: 13 credits per successful conversion (failures do not consume credit).

SVG Converter Create supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://api.codia.ai/v2/open/svg_converter/create' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./logo.png' \
  -F 'file_name=logo.png'
```

Submit a raster image (PNG / JPG / GIF / WebP) for vectorization to **SVG**. The conversion runs asynchronously — call this endpoint to enqueue, then poll `GET /v2/open/svg_converter/result/{record_id}` with the returned `record_id` until the SVG is ready.

## What this API is for

Auto-trace a bitmap into clean vector paths so it scales to any resolution without aliasing. Designed for logos, icons, illustrations, and other flat-art assets — not for photographic content (which doesn't vectorize well by nature).

Typical use cases: rebuilding a missing logo source from a PNG export; preparing assets for print or large-format displays; reducing file size for icon sets; preserving crisp edges in design systems.

## Lifecycle

This is an async, polling-based task (no webhook):

1. **Submit** here. Returns immediately with `data.record_id` (UUID).
2. **Poll** `GET /v2/open/svg_converter/result/{record_id}` with that `record_id`. The result's `svg_convert_status` transitions `3` (doing) → `1` (complete, with `svg_url`) or `2` (failed).
3. **Download** the `.svg` from `svg_url` once complete. URLs are pre-signed; fetch promptly and self-host for long-term use.

Typical end-to-end is **5–30 seconds** depending on detail level. Poll every 1–3 seconds.

## Request

| Field | Required | Notes |
|---|---|---|
| `pic_url` | yes | Public URL of the raster image (PNG / JPG / GIF / WebP). Must be reachable from Codia's network. |
| `file_name` | no | Original file name, used only for record-keeping in your dashboard. |

## Plan limits

Maximum image dimensions and file size depend on your subscription plan. Use `GET /v2/open/svg_converter/limit` at runtime to read your live limits — values below are indicative defaults:

| Plan | Max dimensions | Max file size |
|---|---|---|
| Free | 512×512 | 512 KB |
| Starter | 1024×1024 | 2 MB |
| Pro | 2048×2048 | 4 MB |

## Response

Standard envelope. On 200, `data.record_id` is the UUID you'll need to poll for the result. **Nothing else is returned at this stage** — the SVG itself comes from the `get` endpoint.

## Billing

13 credits per **successful** conversion (deducted when the task completes, not at submission — failed jobs don't consume credit). Uses the unified Codia Open API balance.

## Errors

- `400` — missing `pic_url`, unsupported MIME, or input exceeds your plan's dimensions / file size limits.
- `401` / `403` — auth issues.
- `402` — credits exhausted.
- `429` — rate limit. Back off.
- `500` — internal error; safe to retry.

Returns the maximum input image dimensions and file size your **current subscription plan** allows for `/v2/open/svg_converter/create`, plus the credit cost per conversion. Use this endpoint to validate user uploads before submitting conversion work, or to surface plan limits in your own UI.

## Response

| Field | Unit | Meaning |
|---|---|---|
| `pic_height` | px | Maximum allowed height of the input raster image. |
| `pic_width` | px | Maximum allowed width of the input raster image. |
| `file_size` | bytes | Maximum allowed file size, measured on the raw uploaded file, not base64 text. |
| `layer_credit_unit` | credits | Credits charged per successful conversion. Today this is usually `13`. |

All values reflect live plan state. If the user upgrades or downgrades during a session, call this endpoint again before accepting new uploads.

## Errors

- `401` — missing, invalid, or unauthorized API key.
- `500` — internal error.

Poll for the result of an image-to-SVG conversion task submitted via `POST /v2/open/svg_converter/create`. Returns either an interim status (conversion still running) or a terminal state (complete with download URL, or failed).

## When to call

Poll every **1-3 seconds** until `svg_convert_status` is complete or failed. Typical end-to-end time is **5-30 seconds** depending on image complexity and detail level. Longer runs without progress usually mean the input is unsuitable or the job should be retried.

## Status values

| `svg_convert_status` | Meaning | What `data` carries |
|---|---|---|
| `1` | Complete. | Adds `svg_url` with the generated SVG download link. |
| `2` | Failed. | No SVG URL; show a recoverable error and let the user retry with a cleaner input. |
| `3` | Doing. | Conversion is still in progress; keep polling with backoff. |

## Download semantics

`svg_url` points to a generated SVG asset. Download promptly and self-host the file if your app needs long-term access. The SVG content is plain XML, so callers may also fetch and parse it inline when persistence is not needed.

## Errors

- `400` — `record_id` missing or malformed.
- `401` — missing, invalid, or unauthorized API key.
- `404` — conversion record not found for this API key.
- `429` — polling too aggressively. Back off and respect `Retry-After` when present.
- `500` — transient internal error; retry once with backoff.

Record ID returned by `POST /v2/open/svg_converter/create`.

record_id

List tasks owned by the current API key. When `status` is omitted, the API returns active tasks only: `pending` and `processing`.

Use comma-separated filters, for example `operation=pdf_to_ppt&status=pending,processing&limit=20`. Results are ordered by `created_at` descending. When `has_more` is true, pass the oldest returned task's `created_at` value as `after` to fetch the next page.

Comma-separated operations to include, for example pdf_to_ppt or image_to_design,pdf_to_design.

operation

status

limit

Pagination cursor. Pass the oldest returned created_at timestamp, or an RFC3339 timestamp.

after

Create a Codia Open API asynchronous task. Use this endpoint for every async Open API operation, including PDF to editable PPT.

## Supported operations

| operation | input | credits |
|---|---|---|
| `image_to_design` | `{ "image_url": "https://..." }` | pricing config |
| `pdf_to_design` | `{ "pdf_url": "https://...", "page_no": [0, 1] }` | pricing config per page |
| `pdf_to_ppt` | `{ "upload_id": "upl_...", "page_no": [0, 1], "title": "Deck title" }` or `{ "pdf_url": "https://your-storage/..." }` | pricing config per page |
| `remove_bg` | `{ "image_url": "https://..." }` | pricing config |
| `image_generate` | `{ "prompt": "...", "n": 1, "size": "1024x1024", "model": "..." }` | pricing config per image |
| `image_to_image` | `{ "image_url": "https://...", "prompt": "...", "model": "...", "size": "1024x1024", "quality": "high" }` | pricing config |
| `image_remix` | `{ "image_url": "https://...", "prompt": "...", "size": "1024x1024" }` | pricing config |
| `image_reframe` | `{ "image_url": "https://...", "resolution": "1024x1024" }` | pricing config |
| `image_upscale` | `{ "image_url": "https://...", "model": "..." }` | pricing config |
| `image_object_erase` | `{ "image_url": "https://...", "mask_url": "https://..." }` | pricing config |
| `image_watermark_remove` | `{ "image_url": "https://..." }` | pricing config |
| `image_layering` | `{ "image_url": "https://..." }` | pricing config |
| `image_describe` | `{ "image_url": "https://...", "model": "..." }` | pricing config |
| `image_replace_background` | `{ "image_url": "https://...", "prompt": "...", "model": "..." }` | pricing config |

For private or local PDF-to-PPT inputs, call `POST /v2/open/uploads` first and pass the returned opaque `upload_id`. Codia-managed uploads do not return public file URLs. Use `pdf_url` only for files hosted by your own storage.

## Task ownership

Tasks are scoped to the API key that created them. Use the same API key to query, list, or cancel a task. Other API keys under the same Codia account do not see or control that task.

## Idempotency

Send `Idempotency-Key` on create requests when retries are possible. A repeated request with the same API key, operation, and idempotency key returns the existing task receipt instead of creating duplicate work. Reusing the same key with different `input` or `callback_url` returns HTTP 409. If two identical create requests race, only one task is kept and the duplicate request does not consume extra credits.

## Callback

Optionally pass `callback_url` at the top level. Codia sends a webhook when the task reaches a terminal state. The same URL may also be passed inside `input.callback_url` for compatibility, but the top-level field is preferred.

Send `Idempotency-Key` on create requests when retries are possible. A repeated request with the same API key, operation, and idempotency key returns the existing task receipt instead of creating duplicate work. Reusing the same key with different `input` or `callback_url` returns HTTP 409. If two identical create requests race, only one task is kept and the duplicate request does not consume extra credits.

Existing task receipt returned by idempotency replay

**Cost**: Free — task status query.

Get the latest state for one Open API task. The request must use the same API key that created the task. Terminal states are `succeeded`, `failed`, and `canceled`.

For `pdf_to_ppt`, the successful result contains `result.ppt_url` and may contain `result.note_slide_id`. For `image_to_design` and `pdf_to_design`, `result` contains the same design data shape returned by the existing synchronous endpoints.

task_id

**Cost**: Free — cancellation refunds unused reserved credits.

Cancel a task that is still `pending` or `processing`. The request must use the same API key that created the task. Canceling marks the task `canceled` immediately, refunds unused reserved credits idempotently, and asks the worker to stop when it is running in the current process.

For `pdf_to_ppt`, credits are charged per converted page. If a 15-page task is canceled after 10 pages have already finished conversion, the cancel call refunds 65 credits and the task remains charged for 130 credits. If the task is still pending or has not converted any pages yet, all reserved credits are refunded. Non-page-based tasks refund their full reserved amount when canceled before completion.

The response includes `credits_reserved`, `credits_charged`, and `credits_refunded` so clients can show the final billing outcome.

A `succeeded` task returns HTTP 409 because completed work cannot be canceled. `failed` and `canceled` tasks return 200 with their current state.

Task already succeeded and cannot be canceled

Re-run conversion for selected pages of a succeeded Open API task. This is intended for task outputs that can be improved page-by-page, such as `pdf_to_ppt` image-only pages.

Upload a local PDF for a follow-up Open API task. This endpoint returns an opaque `upload_id`, not a public file URL, so it cannot be used as free public S3 hosting. Pass the `upload_id` to `POST /v2/open/tasks` as `input.upload_id` for `pdf_to_ppt`. The upload is scoped to the same API key and expires after a short retention window.

**Cost**: Free — account query.

Paginated, **call-level** usage history for the unified Codia Open API balance. Each record represents one billable Open API call: which endpoint, when, how many credits, and (if applicable) which model.

Use it for billing reconciliation, building usage dashboards, or surfacing per-feature consumption to your end users. The latest call appears first.

## Query parameters

| Param | Type | Default | Notes |
|---|---|---|---|
| `start_date` | `YYYY-MM-DD` | — | Lower bound (inclusive). Server time zone. Omit for no lower bound. |
| `end_date` | `YYYY-MM-DD` | — | Upper bound (inclusive). Omit for no upper bound. |
| `page` | integer | `1` | 1-indexed page number. |
| `page_size` | integer | `50` | Records per page. Larger pages are slower; pick the smallest size your UI needs. |

## Response shape

Standard envelope. `data` carries `records[]` plus pagination metadata (`page`, `page_size`, `total`). Each `records[i]` minimally has: `endpoint`, `operation_id`, `credits`, `model` (when set), `created_at`. Empty range → empty `records` and `total: 0`, not an error.

## Errors

- `400` — malformed date (must be `YYYY-MM-DD`), or `end_date` before `start_date`.
- `401` — auth issue.
- `500` — internal error.

start_date

end_date

page

page_size

Codia POSTs this event to your `callback_url` when a task reaches `succeeded`, `failed`, or `canceled`. See the Webhook callback section of POST /v2/open/tasks for signature verification and retry behaviour.

HMAC-SHA256 of the raw request body, signed with your API key (right-padded to 32 bytes with NUL if shorter). Format: `sha256=<hex>`.

X-Codia-Signature

Receiver acknowledged the event. Any 2xx status is accepted.