Skip to main content

API Reference

Image → HTML

Pass any mobile screen image and get back pixel-perfect HTML, a structured style guide, and an optional component breakdown. Use the Upload API to host your image on the floow.design CDN first, or pass a public URL or base64 data URL directly.

POST/api/v1/image-to-html🔑 Auth required

Converts a mobile screen image into pixel-perfect HTML. Pass an image URL or base64 data — get back a fully styled, self-contained HTML screen ready to use or export.

  • html is the full screen-ready document — render directly in a 390px-wide iframe.
  • bodyHtml is the unwrapped body content — use this if you want to apply your own shell or compose it with other screens.
  • components is only present when breakdown: true was sent.
  • themeVariables uses CSS custom property names (--primary, --background, etc.) compatible with the floow.design theme system.
  • Deducts 1 credit per call.

Body Parameters

NameTypeDescription
imagestringThe source image. Base64 data URL (data:image/png;base64,...) or any public https:// URL. Supports PNG, JPEG, WEBP, GIF.
labelstringOptional name for this conversion, stored alongside the result.
breakdownbooleanWhen true, the response includes a components array listing every distinct UI component found in the image — type, description, and sub-elements. Default false.
Request body
{  "image": "https://example.com/screenshots/checkout.png",  "label": "Checkout Screen",  "breakdown": true}
Response
{  "id": "clxyz01abc",  "html": "<!DOCTYPE html><html lang=\"en\">...</html>",  "bodyHtml": "<div class=\"bg-background min-h-screen w-full\">...</div>",  "styleGuide": {    "colors": {      "primary": "#6366f1",      "background": "#0f0f11",      "surface": "#1a1a1f",      "foreground": "#f4f4f5",      "muted": "#71717a",      "border": "#27272a"    },    "typography": {      "fontFamily": "Inter, sans-serif",      "headingSize": "24px",      "bodySize": "14px",      "headingWeight": "700",      "bodyWeight": "400"    },    "spacing": {      "containerPadding": "20px",      "cardPadding": "16px",      "gap": "12px"    },    "borderRadius": {      "card": "16px",      "button": "8px",      "badge": "100px"    },    "shadows": ["0 2px 8px rgba(0,0,0,0.12)"],    "themeVariables": {      "--primary": "#6366f1",      "--background": "#0f0f11",      "--foreground": "#f4f4f5",      "--muted": "#71717a",      "--card": "#1a1a1f",      "--border": "#27272a",      "--radius": "16px",      "--font-sans": "Inter, sans-serif"    }  },  "components": [    {      "name": "Order Summary Card",      "type": "card",      "description": "Elevated surface showing item list, subtotal, and total",      "elements": ["item rows", "subtotal row", "discount row", "total row"]    },    {      "name": "Bottom CTA",      "type": "sticky-footer",      "description": "Fixed pay button with price and security badge",      "elements": ["Pay now button", "price label", "lock icon"]    }  ]}

Convert an image

curl https://www.floow.design/api/v1/image-to-html \  -X POST \  -H "Authorization: Bearer fl_your_api_key" \  -H "Content-Type: application/json" \  -d '{    "image": "https://example.com/screenshots/checkout.png",    "label": "Checkout Screen",    "breakdown": true  }'
const res = await fetch("https://www.floow.design/api/v1/image-to-html", {  method: "POST",  headers: {    Authorization: "Bearer fl_your_api_key",    "Content-Type": "application/json",  },  body: JSON.stringify({    image: "https://example.com/screenshots/checkout.png",    label: "Checkout Screen",    breakdown: true,  }),});
if (!res.ok) {  const { error } = await res.json();  throw new Error(error);}
const { id, html, styleGuide, components } = await res.json();
// Render the full screen in a 390px iframedocument.querySelector<HTMLIFrameElement>("#preview")!.srcdoc = html;
// Extract design tokensconsole.log("Primary:", styleGuide.colors.primary);console.log("Font:", styleGuide.typography.fontFamily);components?.forEach((c) => console.log(`${c.name} (${c.type})`));
import requests
response = requests.post(    "https://www.floow.design/api/v1/image-to-html",    headers={        "Authorization": "Bearer fl_your_api_key",        "Content-Type": "application/json",    },    json={        "image": "https://example.com/screenshots/checkout.png",        "label": "Checkout Screen",        "breakdown": True,    },)
response.raise_for_status()data = response.json()
print(f"ID: {data['id']}")print(f"Primary color: {data['styleGuide']['colors']['primary']}")print(f"Font: {data['styleGuide']['typography']['fontFamily']}")
for component in data.get("components", []):    print(f"{component['name']} ({component['type']})")

Convert a local file

async function fileToDataUrl(file: File): Promise<string> {  return new Promise((resolve, reject) => {    const reader = new FileReader();    reader.onload = () => resolve(reader.result as string);    reader.onerror = reject;    reader.readAsDataURL(file);  });}
const input = document.querySelector<HTMLInputElement>('input[type="file"]')!;input.addEventListener("change", async () => {  const file = input.files?.[0];  if (!file) return;
  const dataUrl = await fileToDataUrl(file);
  const res = await fetch("https://www.floow.design/api/v1/image-to-html", {    method: "POST",    headers: {      Authorization: "Bearer fl_your_api_key",      "Content-Type": "application/json",    },    body: JSON.stringify({ image: dataUrl, breakdown: true }),  });
  const { html, styleGuide, components } = await res.json();  console.log(html, styleGuide, components);});
import base64import requests
with open("screenshot.png", "rb") as f:    data_url = "data:image/png;base64," + base64.b64encode(f.read()).decode()
response = requests.post(    "https://www.floow.design/api/v1/image-to-html",    headers={        "Authorization": "Bearer fl_your_api_key",        "Content-Type": "application/json",    },    json={"image": data_url, "label": "My Screen", "breakdown": True},)
response.raise_for_status()data = response.json()print(data["styleGuide"])