NAV
cURL

Introduction

Welcome to the Codia API! You can use our API to access VisualStruct API endpoints, which can recognize images, pdf, psd and other format files and convert them into a unified DSL.

We have language bindings in Shell, Python, and JavaScript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Get Started

Getting started with the Codia API is easy! Follow these three simple steps to begin converting your Screenshots and PDFs into structured designs.

Step 1: Activate Your Subscription

Before you can start using the Codia API, you need to activate a subscription plan. Our API supports two distinct scenarios:

Step 2: Generate Your API Key

Once you've completed your subscription purchase:

  1. Navigate to your Personal Center in your Codia account
  2. Go to the API Keys section to request an API key
  3. Your generated API key will work for both Screenshot and PDF conversion scenarios

API Key Generation

Step 3: Make Your First API Call

You're now ready to start converting your content! Depending on your use case, you can:

Both endpoints are documented below with complete examples and parameter descriptions to help you get started quickly.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "Authorization: Bearer {codia_api_key}"

Make sure to replace {codia_api_key} with your API key.

Codia uses API keys to allow access to the API. You can register a new Codia API key at our developer portal.

Codia expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer {codia_api_key}

VisualStruct API

Convert Image To Design

curl 'https://api.codia.ai/v1/open/image_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --data '{
    "image_url": "your image url"
  }'

The above command returns JSON structured like this:

{
  "code": 0,
  "message": "ok",
  "data": {
    // The Schema Object Here...
  }
}

This endpoint convert image to design.

HTTP Request

POST https://api.codia.ai/v1/open/image_to_design

Request Body

Parameter Default Description
image_url null Image URL that needs to be converted into design.

Convert PDF To Design

curl 'https://api.codia.ai/v1/open/pdf_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --form 'pdf_file=@"xx.pdf"' \
  --form 'page_no="0"'

The above command returns JSON structured like this:

{
  "code": 0,
  "message": "ok",
  "data": {
    "configuration": {
      "scalingFactor": 1,
      "baseWidth": 1940,
      "measurementUnit": "px"
    },
    "pages": [
      {
        // The Schema Object Here...
      }
    ],
    "size": {
      "height": 1080,
      "width": 1940
    }
  }
}

This endpoint convert pdf to design.

HTTP Request

POST https://api.codia.ai/v1/open/pdf_to_design

Request Body

Parameter Default Description
pdf_file null PDF file that needs to be converted into design.
page_no null Pages index of the PDF that need to be converted. Example: [0, 1]

The Schema Object

Overview

The Visual Element Schema is a comprehensive data structure for describing user interface elements and their properties. This schema provides a standardized approach to represent UI components, their layout configurations, styling properties, and content definitions.

Root Structure

{
  "visualElement": {
    // Main UI structure definition
  },
  "configuration": {
    // Global configuration options
  }
}

Top-Level Fields

Field Name Type Description Required
visualElement VisualElement Main UI structure definition Yes
configuration Configuration Global configuration options No

VisualElement Structure

The VisualElement is the core data structure describing a single UI element and its properties.

Basic Fields

Field Name Type Description Required PDF Support
elementId string Unique element identifier Yes
elementName string Element display name Yes
elementType string Element type Yes
displayName string English display name No
layoutConfig LayoutConfiguration Layout configuration Yes
styleConfig VisualStyle or PdfVisualStyle Style configuration Yes
processingMeta ProcessingMetadata Processing metadata Yes
childElements VisualElement[] or PdfVisualElement[] Child elements list No
contentData ElementContent or PdfElementContent Content data No
componentSpec ComponentDefinition Component specification No
boundingBox mixed PDF-specific: Element bounding box coordinates No PDF only
displayOrder number PDF-specific: Element display order No PDF only

Example Structure

{
  "elementId": "element_001",
  "elementName": "Main Container",
  "elementType": "Body",
  "displayName": "Primary Layout Container",
  "layoutConfig": { /* Layout configuration */ },
  "styleConfig": { /* Style configuration */ },
  "processingMeta": { /* Processing metadata */ },
  "childElements": [ /* Child elements */ ],
  "contentData": { /* Content data */ },
  "boundingBox": [0, 0, 100, 100],
  "displayOrder": 1
}

Element Types

Supported UI element types in the schema:

Type Values

Type Description Usage PDF Support
"Body""Container" Page or container root element Main page structure
"Layer""Panel" Generic container for organizing elements Layout containers
"Image""Picture" Image display element Visual content
"Text""Label" Text display element Textual content
"Component""Widget" Reusable custom component Custom components
"Vector""Shape" PDF-specific: Vector graphics element Vector drawings, shapes PDF only
"Group""Collection" PDF-specific: Grouped elements Element collections PDF only

Example

{
  "elementType": "Panel",
  "elementName": "Header Section",
  "displayName": "Top Navigation Area"
}

Layout Configuration

The LayoutConfiguration controls element positioning and layout behavior.

Field Structure

Field Name Type Description Required
positionMode string Positioning mode Yes
flexibleMode string Flexible layout type No
flexAttributes Object Flexible layout attributes No
absoluteAttrs Object Absolute positioning attributes No

Position Modes

Flex Attributes Example

{
  "flexAttributes": {
    "alignItems": "center",
    "justifyContent": "space-between",
    "flexDirection": "column",
    "flexWrap": "nowrap"
  }
}

Absolute Positioning Example

{
  "absoluteAttrs": {
    "align": ["LEFT", "TOP"],
    "coord": [0, 0],
    "orginCoord": [0, 0]
  }
}

Visual Style Configuration

The VisualStyle defines visual styling properties for elements.

Main Style Fields

Field Name Type Description Required PDF Support
widthSpec Object Width specifications Yes
heightSpec Object Height specifications Yes
textConfig Object Text styling configuration No
borderConfig Object Border styling configuration No
backgroundSpec Object Background specifications No
effectsList Array Visual effects list No
textColor VisualColor Text color settings No
paddingValues mixed Padding values No
opacityLevel number Opacity level (0-255) No
overflowMode Array Overflow handling mode No
rotationAngle number Rotation angle in degrees No
textDetection Object Text detection metadata No
textExtraction Object Text extraction metadata No

PDF-Specific Style Fields

The following fields are available only in PDF processing scenarios:

Field Name Type Description Source Field
characterData Object PDF-specific: Character-level styling data chars
transformMatrix number[] PDF-specific: Transformation matrix transform
cornerRadius number PDF-specific: Corner radius value radius
isRightToLeft boolean PDF-specific: Right-to-left text direction arabic
extendedMatrix string PDF-specific: Extended transformation matrix ex_transform

Size Configuration

{
  "widthSpec": {
    "sizing": "FIXED",    // FIXED, FILL, FIT_CONTENT
    "value": 100
  },
  "heightSpec": {
    "sizing": "FILL",
    "value": 200
  }
}

Text Configuration

{
  "textConfig": {
    "fontSize": 16,
    "fontStyle": "normal",        // normal, bold, italic, semi_bold
    "textAlign": ["LEFT", "CENTER"],
    "fontFamily": "Arial",
    "lineHeight": 1.5,
    "letterSpacing": 0
  }
}

Border Configuration

{
  "borderConfig": {
    "borderWidth": 2,
    "borderStyle": "solid",
    "borderColor": {
      "rgbValues": [128, 128, 128],
      "hexCode": "#808080"
    },
    "borderRadius": [10, 10, 10, 10]
  }
}

Background Specifications

Solid Color Background

{
  "backgroundSpec": {
    "type": "COLOR",
    "backgroundColor": {
      "rgbValues": [255, 255, 255],
      "hexCode": "#ffffff"
    }
  }
}

Image Background

{
  "backgroundSpec": {
    "type": "IMAGE",
    "imageUrl": "https://example.com/bg.jpg",
    "backgroundSize": "cover",
    "backgroundPosition": "center",
    "backgroundRepeat": "no-repeat"
  }
}

Gradient Background

{
  "backgroundSpec": {
    "type": "LINEAR_GRADIENT",
    "deg": 45,
    "gradientStops": [
      {"color": {"rgbValues": [255, 0, 0]}, "position": 0},
      {"color": {"rgbValues": [0, 0, 255]}, "position": 100}
    ]
  }
}

PDF-Specific Style Example

{
  "styleConfig": {
    "widthSpec": {"sizing": "FIXED", "value": 200},
    "heightSpec": {"sizing": "FIXED", "value": 100},
    "characterData": {
      "0": {"size": 12, "fontFamily": "Arial"},
      "1": {"size": 14, "fontFamily": "Bold"}
    },
    "transformMatrix": [1.0, 0.0, 0.0, 1.0, 50.0, 100.0],
    "cornerRadius": 5,
    "isRightToLeft": false,
    "extendedMatrix": "matrix(1,0,0,1,0,0)"
  }
}

Color Definition

The VisualColor structure supports multiple color representation formats.

Color Fields

Field Name Type Description Example
rgbValues number[] RGB values array [255, 128, 0]
hexCode string Hexadecimal color code "#ff8000"

Example

{
  "rgbValues": [255, 128, 0],
  "hexCode": "#ff8000"
}

Element Content

The ElementContent defines the actual content of elements.

Content Fields

Field Name Type Description Applicable Elements PDF Support
textValue string Text content Text
imageSource string Image URL source Image
colorReference string Color token reference Any
componentReference string Component reference ID Component
componentAttributes Object Component attributes Component

PDF-Specific Content Fields

The following content fields are available only in PDF processing scenarios:

Field Name Type Description Source Field Applicable Elements
vectorData VectorData PDF-specific: Vector graphics data vector Vector/Shape
maskingMode string PDF-specific: Masking mode maskType Any
blendingType string PDF-specific: Blending mode blendMode Any
svgTemplate string PDF-specific: SVG template string svgTemplate Vector/Shape
imageData string PDF-specific: Base64 encoded image data imageBase64 Image

Content Examples

Text Content

{
  "textValue": "Welcome to our platform",
  "colorReference": "primary_text_color"
}

Image Content

{
  "imageSource": "https://example.com/hero-image.jpg",
  "imageData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ..."
}

PDF Vector Content

{
  "vectorData": {
    "pathItems": [
      {
        "pathType": "l",
        "coordinates": [
          {"xPosition": 0, "yPosition": 0},
          {"xPosition": 100, "yPosition": 100}
        ]
      }
    ],
    "evenOddRule": false,
    "layerIndex": 1,
    "vectorType": "path",
    "strokeOpacity": 1.0,
    "strokeColor": {
      "rgbValues": [0, 123, 255],
      "hexCode": "#007bff"
    },
    "strokeWidth": 2.0,
    "lineCapStyle": "round",
    "lineJoinStyle": "round",
    "isClosedPath": false
  },
  "maskingMode": "normal",
  "blendingType": "multiply"
}

Component Content

{
  "componentReference": "button_primary",
  "componentAttributes": {
    "variant": {"type": "primary"},
    "size": {"value": "large"},
    "action": {"handler": "submitForm"}
  }
}

PDF Vector Data Structure

Note: The following structures are specific to PDF processing scenarios.

VectorData Structure

Field Name Type Description Source Field
pathItems PathItem[] Array of path elements items
evenOddRule boolean Even-odd fill rule even_odd
layerDepth string Layer depth identifier level
layerIndex number Layer index number layer
vectorType string Vector type identifier type
strokeOpacity number Stroke opacity (0.0-1.0) stroke_opacity
strokeColor VisualColor Stroke color color
fillColor VisualColor Fill color fill
fillOpacity number Fill opacity (0.0-1.0) fill_opacity
lineCapStyle string Line cap style lineCap
lineJoinStyle string Line join style lineJoin
dashPattern number[] Dash pattern array dashes
strokeWidth number Stroke width lineWidth
isClosedPath boolean Whether path is closed closePath

PathItem Structure

Field Name Type Description Source Field
pathType string Path type ("l" for line, "c" for curve) vector_type
coordinates PositionData[] Array of position coordinates points

PositionData Structure

Field Name Type Description Source Field
xPosition number X coordinate x
yPosition number Y coordinate y

PDF Vector Example

{
  "vectorData": {
    "pathItems": [
      {
        "pathType": "l",
        "coordinates": [
          {"xPosition": 50.0, "yPosition": 50.0},
          {"xPosition": 250.0, "yPosition": 50.0}
        ]
      },
      {
        "pathType": "c",
        "coordinates": [
          {"xPosition": 250.0, "yPosition": 50.0},
          {"xPosition": 275.0, "yPosition": 25.0},
          {"xPosition": 275.0, "yPosition": 75.0},
          {"xPosition": 250.0, "yPosition": 100.0}
        ]
      }
    ],
    "evenOddRule": false,
    "layerIndex": 1,
    "vectorType": "path",
    "strokeOpacity": 1.0,
    "strokeColor": {
      "rgbValues": [0, 123, 255],
      "hexCode": "#007bff"
    },
    "fillColor": {
      "rgbValues": [255, 255, 255],
      "hexCode": "#ffffff"
    },
    "fillOpacity": 0.5,
    "lineCapStyle": "round",
    "lineJoinStyle": "round",
    "dashPattern": [5, 3],
    "strokeWidth": 2.0,
    "isClosedPath": false
  }
}

Component Definition

The ComponentDefinition structure for reusable components.

Component Fields

Field Name Type Description
componentId string Component identifier
componentName string Component display name
sourceCode string Component implementation code
configOptions Object Configuration options schema

Example

{
  "componentId": "interactive_button",
  "componentName": "Interactive Button Component",
  "sourceCode": "/* React component implementation */",
  "configOptions": {
    "variant": "string",
    "size": "string",
    "disabled": "boolean",
    "onClick": "function"
  }
}

Processing Metadata

The ProcessingMetadata contains technical processing information.

Metadata Fields

Field Name Type Description
surfaceArea number Element surface area in pixels
detectionScore number Detection confidence score (0.0-1.0)
textContainerized boolean Whether text is containerized

Example

{
  "surfaceArea": 960000,
  "detectionScore": 0.95,
  "textContainerized": true
}

Global Configuration

The Configuration object contains global settings.

Configuration Fields

Field Name Type Description Default
baseWidth number Base design width 375
measurementUnit string Measurement unit "px"
scalingFactor number Scaling factor 1

Example

{
  "baseWidth": 782,
  "measurementUnit": "px",
  "scalingFactor": 1
}

Field Mapping Reference

Standard to Masked Field Mappings

Basic Fields

Original Field Masked Field Notes
id elementId Element identifier
name elementName Element name
type elementType Element type (mapped)
enName displayName English display name
children childElements Child elements array
layout layoutConfig Layout configuration
style styleConfig Style configuration
i2dExt processingMeta Processing metadata
content contentData Content data
component componentSpec Component specification

PDF-Specific Field Mappings

Original Field Masked Field Context Notes
sortIndex displayOrder Basic Display order
rectanglePoint boundingBox Basic Bounding box coordinates
chars characterData Style Character-level styling
transform transformMatrix Style Transformation matrix
radius cornerRadius Style Corner radius
arabic isRightToLeft Style Text direction
ex_transform extendedMatrix Style Extended transformation
vector vectorData Content Vector graphics data
maskType maskingMode Content Masking mode
blendMode blendingType Content Blending type
svgTemplate svgTemplate Content SVG template
imageBase64 imageData Content Base64 image data

Vector Data Field Mappings (PDF-Specific)

Original Field Masked Field Notes
items pathItems Path items array
even_odd evenOddRule Even-odd fill rule
level layerDepth Layer depth
layer layerIndex Layer index
vector_type pathType Path type
points coordinates Coordinates array
x xPosition X coordinate
y yPosition Y coordinate
stroke_opacity strokeOpacity Stroke opacity
fill_opacity fillOpacity Fill opacity
lineCap lineCapStyle Line cap style
lineJoin lineJoinStyle Line join style
dashes dashPattern Dash pattern
lineWidth strokeWidth Stroke width
closePath isClosedPath Path closure flag

Element Type Mappings

Original Type Masked Type Context
Body Container All
Layer Panel All
Image Picture All
Text Label All
Component Widget All
Vector Shape PDF-specific
Group Collection PDF-specific

Complete Example

PDF Document Structure Example

{
  "visualElement": {
    "elementId": "pdf_page_1",
    "elementName": "PDF Document Page",
    "elementType": "Panel",
    "displayName": "First Page",
    "displayOrder": 0,
    "boundingBox": [0, 0, 595, 842],
    "layoutConfig": {
      "positionMode": "Normal",
      "flexibleMode": "Absolute"
    },
    "styleConfig": {
      "widthSpec": {"sizing": "FIXED", "value": 595},
      "heightSpec": {"sizing": "FIXED", "value": 842},
      "backgroundSpec": {
        "type": "COLOR",
        "backgroundColor": {"rgbValues": [255, 255, 255]}
      }
    },
    "processingMeta": {
      "surfaceArea": 501490,
      "detectionScore": 0.92,
      "textContainerized": false
    },
    "childElements": [
      {
        "elementId": "vector_diagram",
        "elementName": "Process Diagram",
        "elementType": "Shape",
        "displayOrder": 1,
        "layoutConfig": {
          "positionMode": "Absolute",
          "absoluteAttrs": {
            "align": ["LEFT", "TOP"],
            "coord": [50, 100]
          }
        },
        "styleConfig": {
          "widthSpec": {"sizing": "FIXED", "value": 300},
          "heightSpec": {"sizing": "FIXED", "value": 200}
        },
        "processingMeta": {
          "surfaceArea": 60000,
          "detectionScore": 0.89,
          "textContainerized": false
        },
        "contentData": {
          "vectorData": {
            "pathItems": [
              {
                "pathType": "l",
                "coordinates": [
                  {"xPosition": 50.0, "yPosition": 50.0},
                  {"xPosition": 250.0, "yPosition": 50.0}
                ]
              }
            ],
            "evenOddRule": false,
            "layerIndex": 1,
            "vectorType": "path",
            "strokeOpacity": 1.0,
            "strokeColor": {
              "rgbValues": [0, 123, 255],
              "hexCode": "#007bff"
            },
            "strokeWidth": 2.0,
            "lineCapStyle": "round",
            "lineJoinStyle": "round",
            "isClosedPath": false
          }
        }
      }
    ]
  },
  "configuration": {
    "baseWidth": 595,
    "measurementUnit": "pt",
    "scalingFactor": 1
  }
}

Codia Figma SDK

Overview

Automatically generate Figma designs from UI screenshots. Call the Codia API to get design data, then generate corresponding components in Figma.

Usage Flow

1. Plugin UI (ui.html)

Create the plugin user interface with a button to trigger design generation. When users click the button, it calls the Codia API to fetch design data and sends the data to the plugin main thread for processing.

<!DOCTYPE html>
<html>
  <head>
    <title>Codia Design Generator</title>
  </head>
  <body>
    <button id="generateBtn">Generate Design</button>

    <script>
      const generateBtn = document.getElementById("generateBtn");

      // Configuration
      const CODIA_API_KEY = "YOUR_API_KEY_HERE";
      const IMAGE_URL = "https://your-image-url.com/screenshot.png";

      // Call Codia API to get design data
      async function fetchDSLFromCodia() {
        try {
          const response = await fetch(
            "https://api.codia.ai/v1/open/image_to_design",
            {
              method: "POST",
              headers: {
                Authorization: `Bearer ${CODIA_API_KEY}`,
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
                image_url: IMAGE_URL,
              }),
            }
          );

          if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
          }

          const data = await response.json();

          if (data.code !== 0) {
            throw new Error(data.message || "API request failed");
          }

          return data.data.visualElement;
        } catch (error) {
          console.error("Failed to fetch DSL from Codia:", error);
          throw error;
        }
      }

      // Generate design on button click
      generateBtn.addEventListener("click", async () => {
        try {
          const designData = await fetchDSLFromCodia();
          if (!designData) {
            return;
          }

          // Send message to plugin main thread
          parent.postMessage(
            {
              pluginMessage: {
                type: "generate-design",
                data: designData,
              },
            },
            "*"
          );
        } catch (error) {
          console.error("Error:", error);
        }
      });

      // Listen for plugin main thread responses
      window.addEventListener("message", (event) => {
        const msg = event.data.pluginMessage;
        if (msg && msg.type === "design-result") {
          if (msg.success) {
            console.log("Design generation successful!");
          } else {
            console.error("Generation failed:", msg.error);
          }
        }
      });
    </script>
  </body>
</html>

2. Install Dependencies

Install the Codia SDK dependency package, which provides core functionality for converting design data into Figma designs.

npm install figma-image-to-design

3. Plugin Main Thread Code (code.ts)

Write the plugin main thread code that handles receiving messages from the UI, processes design data using the Codia SDK, and generates corresponding Figma designs.

// Import Codia SDK
import { DesignGenerator } from "figma-image-to-design";

// Show plugin UI
figma.showUI(__html__, { width: 300, height: 200 });

// Listen to messages from UI
figma.ui.onmessage = async (msg) => {
  if (msg.type === "generate-design") {
    try {
      // Use Codia SDK to generate design
      const result = await DesignGenerator.generateFromVisualElement(msg.data);

      if (result.status === "SUCCESS") {
        // Send success message back to UI
        figma.ui.postMessage({
          type: "design-result",
          success: true,
          result: result,
        });
      } else {
        // Send failure message back to UI
        figma.ui.postMessage({
          type: "design-result",
          success: false,
          error: result.message,
        });
      }
    } catch (error) {
      // Send error message back to UI
      figma.ui.postMessage({
        type: "design-result",
        success: false,
        error: error.message,
      });
    }
  }
};

Result Structure

interface DesignGenerateResult {
  message: string; // Result message
  statusCode: number; // Status code
  status: "SUCCESS" | "SCRIPT_ERROR" | "CONVERSION_ERROR"; // Generation status
}

Core Flow

  1. UI sends message: User clicks button → Fetch API data → Send to main thread via parent.postMessage()
  2. Main thread receives: figma.ui.onmessage listens for messages → Process data to generate design
  3. Result feedback: Main thread sends result back to UI via figma.ui.postMessage()

Notes

Demo Project

To help developers quickly integrate Codia SDK, we provide a complete Figma plugin project.

Download codia-sdk-demo.zip

The project includes complete plugin source code, UI interface, pre-configured build environment (Webpack + TypeScript), and Codia API integration examples.

After downloading and extracting, follow the README.md in the project root directory to get started quickly.

Errors

The Codia API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
402 PaymentRequired -- Your credit is insufficient.
403 Forbidden -- The api requested is hidden for administrators only.
404 Not Found -- The specified api could not be found.
405 Method Not Allowed -- You tried to access an api with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- You're requesting too many images! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.