Codia Open API

Codia Open API packages Codia Open API endpoints as local agent tools. Install the runtime CLI and the public skills pack, authenticate once, then let Codex, Claude, Cursor, or another local workflow call Codia APIs with files from your machine.

Use it when you want an agent to convert screenshots into design JSON, extract PDF layouts, convert PDFs to PPTX, remove backgrounds, generate or edit images, vectorize assets, and inspect credits or usage without manually writing REST calls.

Prerequisites

Node.js 20 or later
A Codia account with Open API access
A Codia Open API key from Dashboard > Developers
Open API credits for paid endpoints

Quickstart

bash

npm install -g @codia-ai/codia-design-cli
npx -y skills add codia-ai/codia-design-skills -g -y
codia-design auth login --platform codex
codia-design credits

The npx skills add ... command installs one top-level codia-design-skills root skill pack for supported local agents. There is no separate template-install step in the current release.

If browser login is unavailable, bind an API key directly:

bash

codia-design auth set --api-key api_key_xxx

Authentication

The most reliable setup is binding an API key directly:

bash

codia-design auth set --api-key api_key_xxx
codia-design auth status

For CI or ephemeral agent environments, avoid writing local config and pass the key through an environment variable:

bash

export CODIA_API_KEY=api_key_xxx
codia-design credits

When browser authorization is available in your environment, you can also use:

bash

codia-design auth login --platform codex

The CLI stores local credentials in ~/.codia/design-skills/config.json. Do not paste this file into prompts, logs, or support tickets.

First Successful Call

Run a low-risk account call first:

bash

codia-design credits
codia-design usage --page 1 --page_size 20

Then test a file workflow:

bash

codia-design image-to-design --image ./screenshot.png --out design.json

Local image and PDF paths are supported. Image-processing commands send local images directly to their target multipart APIs; URL inputs continue to use JSON mode.

Common Workflows

bash

codia-design image-to-design --image ./screenshot.png --out design.json
codia-design pdf-to-design --pdf ./file.pdf --pages 0,1 --out result.json
codia-design pdf-to-ppt --pdf ./file.pdf --pages 0 --title "Deck" --poll --out deck.json
codia-design remove-bg --image ./product.png --out cutout.json
codia-design image generate --prompt "modern SaaS dashboard hero" --size 1024x1024
codia-design image upscale --image ./image.png
codia-design image replace-bg --image ./product.png --prompt "clean white studio background"
codia-design image describe --image ./image.png
codia-design svg create --image ./logo.png

Use --out result.json for large responses so the agent can read the result in a follow-up step.

Agent Skill Installation

Target	Command	Notes
Runtime CLI	`npm install -g @codia-ai/codia-design-cli`	Provides the `codia-design` command.
Agent skills	`npx -y skills add codia-ai/codia-design-skills -g -y`	Installs the public Codia Design Skills root pack.
GitHub URL	`npx -y skills add https://github.com/codia-ai/codia-design-skills.git -g -y`	Equivalent explicit repository URL form.
No global CLI install	`npx -y @codia-ai/codia-design-cli --help`	Useful for one-off verification or locked-down environments.

Credits, Usage, and Auto Recharge

All public Open API endpoints share one Codia Open API balance. Buy or subscribe to the unified API credits SKU once, then spend the same balance across image-to-design, PDF-to-design, PDF-to-PPT, image processing, SVG conversion, and background removal.

bash

codia-design credits
codia-design usage --page 1 --page_size 20
codia-design auto-recharge get
codia-design auto-recharge set --enabled true --threshold 100 --credits 1000 --monthly_max 5000

Auto recharge is optional. Use it for production workflows where an agent should not stop when credits drop below a threshold.

Command Reference

CLI command	Open API endpoint
`image-to-design`	POST`/v2/open/image_to_design`
`pdf-to-design`	POST`/v2/open/pdf_to_design`
`pdf-to-ppt`	POST`/v2/open/tasks` and GET`/v2/open/tasks/{task_id}`
`remove-bg`	POST`/v2/open/remove_bg`
`credits`	GET`/v2/open/credits`
`usage`	GET`/v2/open/usage`
`auto-recharge get`	GET`/v2/open/auto_recharge`
`auto-recharge set`	POST`/v2/open/auto_recharge`
`image generate`	POST`/v2/open/image/generate_image`
`image upscale`	POST`/v2/open/image/upscale`
`image replace-bg`	POST`/v2/open/image/replace_background`
`image object-erase`	POST`/v2/open/image/object_erase`
`image describe`	POST`/v2/open/image/describe`
`image watermark-remove`	POST`/v2/open/image/watermark_remove`
`image image-to-image`	POST`/v2/open/image/image_to_image`
`image remix`	POST`/v2/open/image/remix`
`image reframe`	POST`/v2/open/image/reframe`
`image layering`	POST`/v2/open/image/layering`
`svg create`	POST`/v2/open/svg_converter/create`
`svg get`	GET`/v2/open/svg_converter/result/{record_id}`
`svg limit`	GET`/v2/open/svg_converter/limit`

Local image commands including image-to-design, remove-bg, image upscale, image replace-bg, image object-erase, image describe, image watermark-remove, image image-to-image, image remix, image reframe, image layering, and svg create send local files directly to the target endpoint with multipart/form-data. Codia checks credits before reading and uploading the file. Passing an https://... image still uses the existing JSON URL mode.

Troubleshooting

verify failed, invalid key: the configured API key is not accepted by the target Open API environment. Create a new key in Dashboard > Developers and run codia-design auth set --api-key ....
Missing API key: run codia-design auth set --api-key ..., codia-design auth login --platform codex, or set CODIA_API_KEY.
not found: the endpoint is not deployed in the selected --base-url environment yet, or the CLI version is ahead of the backend.
Upload fails for a local file: confirm the file exists, is a supported image or PDF type, and the target environment has the multipart endpoint deployed.
402 or insufficient credits: buy or subscribe to Codia Open API, then retry.
429: reduce concurrency or retry after the rate limit window.
Large JSON responses: pass --out result.json so the agent can read the file in a follow-up step.