Codia Open API

Codia Open API 把 Codia Open API endpoint 封装成本地 Agent 工具。你需要分别安装运行时 CLI 和公开 skills pack，完成一次认证后，就可以让 Codex、Claude、Cursor 或其他本地工作流直接调用 Codia API，并读取本机文件。

它适合这些场景：让 Agent 把截图转成设计 JSON、解析 PDF 页面结构、把 PDF 转成 PPTX、去背景、生成或编辑图片、把图片转 SVG，以及查询 credits 和调用明细。

前置条件

Node.js 20 或以上
拥有 Open API 权限的 Codia 账号
在 Dashboard > Developers 创建的 Codia Open API key
可用于付费 endpoint 的 Open API credits

快速开始

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

npx skills add ... 会安装一个顶层 codia-design-skills root skill pack，供支持的本地 Agent 使用。当前版本不再需要单独的模板安装步骤。

如果当前环境不能使用浏览器登录，可以直接绑定 API key：

bash

codia-design auth set --api-key api_key_xxx

认证

最稳定的方式是直接绑定 API key：

bash

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

在 CI 或临时 Agent 环境里，可以不写本地配置，直接通过环境变量传入：

bash

export CODIA_API_KEY=api_key_xxx
codia-design credits

当浏览器授权流程可用时，也可以使用：

bash

codia-design auth login --platform codex

CLI 会把本地凭证保存在 ~/.codia/design-skills/config.json。不要把这个文件粘贴到 prompt、日志或支持工单里。

第一次成功调用

建议先跑低风险的账号查询：

bash

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

然后再测试文件类工作流：

bash

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

CLI 支持本地图片和 PDF 路径。图片处理命令会把本地图片直接发送到目标 multipart API；传入 URL 时仍使用 JSON 模式。

常用工作流

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

对于较大的返回结果，建议使用 --out result.json 写入文件，方便 Agent 后续继续读取。

Agent Skill 安装

目标	命令	说明
运行时 CLI	`npm install -g @codia-ai/codia-design-cli`	提供 `codia-design` 命令。
Agent skills	`npx -y skills add codia-ai/codia-design-skills -g -y`	安装公开 Codia Design Skills root pack。
GitHub URL	`npx -y skills add https://github.com/codia-ai/codia-design-skills.git -g -y`	等价的完整仓库 URL 写法。
不全局安装 CLI	`npx -y @codia-ai/codia-design-cli --help`	适合一次性验证或受限环境。

Credits、用量和自动充值

所有公开 Open API endpoint 共用同一个 Codia Open API 余额。用户只需要购买或订阅统一的 API credits SKU，就可以在 image-to-design、PDF-to-design、PDF-to-PPT、图片处理、SVG 转换和去背景之间通用。

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

自动充值是可选能力。对于生产 Agent 工作流，可以用它避免 credits 低于阈值后任务中断。

命令对应关系

CLI 命令	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` 和 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`

本地图片命令包括 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 和 svg create，都会用 multipart/form-data 直接发送到目标 endpoint。Codia 会先校验 credits，再读取并上传文件。传入 https://... 图片时仍使用现有 JSON URL 模式。

常见问题排查

verify failed, invalid key：当前 API key 没有被目标 Open API 环境接受。请在 Dashboard > Developers 创建新 key，然后运行 codia-design auth set --api-key ...。
Missing API key：运行 codia-design auth set --api-key ...、codia-design auth login --platform codex，或设置 CODIA_API_KEY。
not found：目标 --base-url 环境还没有部署该 endpoint，或 CLI 版本领先于后端版本。
本地文件上传失败：确认文件存在、图片或 PDF 格式受支持，并且目标环境已部署对应 multipart endpoint。
402 或 credits 不足：购买或订阅 Codia Open API 后重试。
429：降低并发，或在 rate limit 窗口后重试。
大 JSON 返回：使用 --out result.json 写入文件，方便 Agent 后续继续读取。