Skip to main content

API Reference

Upload

Upload a mobile screenshot or design image to the floow.design CDN. The returned URL can be passed directly to the Image → HTML API — no need to host images yourself.

Recommended flow: Upload an image → get a CDN URL → pass the URL to POST /api/v1/image-to-html. This avoids embedding large base64 strings in your API calls and lets you reuse the same image across multiple conversions.

POST/api/v1/upload🔑 Auth required

Upload an image file to the floow.design CDN. Accepts multipart/form-data (binary file) or application/json (base64 data URL). Returns a permanent CDN URL and a record ID.

  • Supported formats: PNG, JPEG, WEBP, GIF. Maximum file size: 10 MB.
  • Images are stored under the image-to-html/ path on the floow.design Vercel Blob CDN.
  • The url is permanent and publicly readable — safe to pass to image-to-html.
  • No credits are deducted for uploads — only the subsequent image-to-html call costs 1 credit.
  • Use multipart/form-data (file field) for browser/mobile uploads. Use JSON + base64 for server-to-server.

Body Parameters

NameTypeDescription
fileFile (multipart)Binary image file sent as multipart/form-data with field name file. Use this for direct file uploads from a browser or CLI.
imagestring (JSON)Base64 data URL — data:image/png;base64,... Send as application/json. Either file or image must be provided.
filenamestring (JSON)Optional filename hint when using the JSON/base64 mode. Stored for reference only.
Response
{  "id": "clxyz01abc",  "url": "https://kpjfmdco8hzsojpq.public.blob.vercel-storage.com/image-to-html/1744450000000-a1b2c3-checkout-screen.png",  "filename": "checkout-screen.png",  "contentType": "image/png",  "size": 284320,  "createdAt": "2026-04-12T10:00:00Z"}

Upload a file (multipart)

The most efficient method for browser inputs and CLI tools. The TypeScript example chains directly into the Image → HTML API.

curl https://www.floow.design/api/v1/upload \  -X POST \  -H "Authorization: Bearer fl_your_api_key" \  -F "file=@/path/to/screenshot.png"
const form = new FormData();form.append("file", file); // File from <input type="file"> or Blob
const res = await fetch("https://www.floow.design/api/v1/upload", {  method: "POST",  headers: { Authorization: "Bearer fl_your_api_key" },  body: form,});
if (!res.ok) {  const { error } = await res.json();  throw new Error(error);}
const { url, id } = await res.json();
// Pass the URL directly to Image → HTMLconst htmlRes = 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: url, breakdown: true }),});
const { html, styleGuide, components } = await htmlRes.json();
import requests
# Step 1 — upload the imagewith open("screenshot.png", "rb") as f:    upload_res = requests.post(        "https://www.floow.design/api/v1/upload",        headers={"Authorization": "Bearer fl_your_api_key"},        files={"file": ("screenshot.png", f, "image/png")},    )
upload_res.raise_for_status()url = upload_res.json()["url"]print(f"Uploaded: {url}")
# Step 2 — convert to HTMLhtml_res = requests.post(    "https://www.floow.design/api/v1/image-to-html",    headers={        "Authorization": "Bearer fl_your_api_key",        "Content-Type": "application/json",    },    json={"image": url, "breakdown": True},)
html_res.raise_for_status()data = html_res.json()print(data["styleGuide"]["colors"]["primary"])

Upload via base64 (JSON)

Use this if your image is already in memory as a base64 string or data URL.

# Encode image to base64 firstB64=$(base64 -i /path/to/screenshot.png)
curl https://www.floow.design/api/v1/upload \  -X POST \  -H "Authorization: Bearer fl_your_api_key" \  -H "Content-Type: application/json" \  -d "{\"image\":\"data:image/png;base64,${B64}\"}"
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 dataUrl = await fileToDataUrl(file);
const res = await fetch("https://www.floow.design/api/v1/upload", {  method: "POST",  headers: {    Authorization: "Bearer fl_your_api_key",    "Content-Type": "application/json",  },  body: JSON.stringify({    image: dataUrl,    filename: "checkout-screen.png",  }),});
const { url } = await res.json();
import base64import requests
with open("screenshot.png", "rb") as f:    data_url = "data:image/png;base64," + base64.b64encode(f.read()).decode()
res = requests.post(    "https://www.floow.design/api/v1/upload",    headers={        "Authorization": "Bearer fl_your_api_key",        "Content-Type": "application/json",    },    json={"image": data_url, "filename": "checkout-screen.png"},)
res.raise_for_status()url = res.json()["url"]print(f"CDN URL: {url}")