Codia Image To Design

codia-image-to-design

Runtime And Auth

Use the local codia-design CLI for this feature. Before calling the API, verify that codia-design is available. If it is missing and global npm installs are allowed, install it with npm install -g @codia-ai/codia-design-cli. Then check codia-design auth status; if it is not connected, run codia-design auth login --platform codex or bind an API key with codia-design auth set --api-key api_key_xxx. Never print API keys or ~/.codia/design-skills/config.json.

Convert UI screenshots into editable hierarchical design trees (VisualElement trees).

CLI Command

# Synchronous direct conversion
codia-design image-to-design --image <PATH|URL> [--out FILE]

# Asynchronous task submit
codia-design image-to-design --image <HTTPS_URL> --async [--callback URL] [--idempotency KEY] [--out task.json]

# Asynchronous task submit and poll
codia-design image-to-design --image <HTTPS_URL> --poll [--timeout 300000] [--out result.json]

Parameters

Sync vs Async Selection

Use synchronous POST /v2/open/image_to_design for one image, especially local files and images below 2K on the longest edge. It keeps the result in a single request and supports direct multipart upload for local files.

Use asynchronous POST /v2/open/tasks with operation: "image_to_design" for multiple images, images at 2K or above, or flows that need callback/idempotency/retry behavior. Submit one task per image. Task mode currently accepts input.image_url, so the CLI requires --image to be a public HTTPS URL in --async or --poll mode. For a local large image, upload it to user-owned storage/CDN first and pass that URL, or use synchronous mode if the expected runtime is acceptable.

Response

Synchronous mode and completed --poll mode return the design data. --poll also includes task metadata fields such as task_id, operation, status, and progress.

{
  "ok": true,
  "data": {
    "configuration": {
      "scalingFactor": 1.0,
      "baseWidth": 375,
      "measurementUnit": "px"
    },
    "visualElement": {
      "elementId": "root_001",
      "elementName": "Body",
      "elementType": "Body",
      "layoutConfig": { "positionMode": "Normal" },
      "styleConfig": {
        "widthSpec":  { "sizing": "FIXED", "value": 375 },
        "heightSpec": { "sizing": "FIXED", "value": 812 }
      },
      "contentData": null,
      "processingMeta": { "detectionScore": 1.0, "surfaceArea": 304500 },
      "childElements": []
    }
  }
}

configuration field

VisualElement node structure

Every node (including the visualElement root node and all childElements) has the same schema:

elementType value

layoutConfig key fields

positionMode: "Flex" | "Absolute" | "Normal" | "Relative"

• "Flex" — Participate in the flex layout of the parent node. The parent node’s flexAttributes describe the direction/alignment
• "Absolute" — absolute positioning, read absoluteAttrs.coord.x / .y to get the offset
• flexAttributes: { flexDirection, alignItems, justifyContent, flexWrap } (on Flex container)

styleConfig key fields

Usage Example

# Synchronous local file, recommended for a single small image
codia-design image-to-design --image ./screenshot.png --out result.json

# Synchronous URL
codia-design image-to-design --image https://example.com/screen.png --out result.json

# Submit an async task for a large image and return task_id
codia-design image-to-design --image https://example.com/large-screen.png --async --out task.json

# Submit and wait for completion
codia-design image-to-design --image https://example.com/large-screen.png --poll --timeout 300000 --out result.json

Traverse the tree after reading the results (Node.js):

const { data } = require('./result.json');
const { scalingFactor } = data.configuration;

function walk(node, depth = 0) {
  const pad = '  '.repeat(depth);
  if (node.elementType === 'Text') {
    console.log(pad + '[Text]', node.contentData?.textValue);
  } else if (node.elementType === 'Image') {
    console.log(pad + '[Image]', node.contentData?.imageSource);
  } else {
    console.log(pad + '[' + node.elementType + ']', node.elementName);
  }
  node.childElements?.forEach(c => walk(c, depth + 1));
}
walk(data.visualElement);

//Extract all text nodes
function extractText(node, results = []) {
  if (node.elementType === 'Text') results.push(node.contentData?.textValue);
  node.childElements?.forEach(c => extractText(c, results));
  return results;
}

Low confidence node filtering (processingMeta.detectionScore < 0.5) is recommended for use in production code.

Input Limits

The maximum size and file size of input images depend on the plan level:

Errors & Billing

Credits: 13 credits/request. After the command completes, the CLI checks available_credits and reminds the user if the remaining balance is below 26 credits (2x estimate); this does not block generation. Duration: synchronous mobile screenshots are usually < 10s, desktop intensive pages are longer. Prefer async task mode for large images, 2K+ images, and batches.