Makistry Generation API

Makistry's Generation API converts text prompts and images into production-ready 3D CAD files (STEP, STL, GLB, 3MF). Each request runs as an async job — you submit, get a job_id, then poll or receive a webhook when the file is ready.

Base URL: https://api.makistry.ai/v1

Dashboard: api.makistry.ai — manage keys, view jobs, download files, monitor billing.

Quick Start

This walkthrough takes you from zero to a downloaded STEP file in three steps.

Step 1 — Get an API key

Create a key at the dashboard. Copy the api_key — it's shown only once.

Step 2 — Submit a job

curl

# requires jq — install with: brew install jq  (macOS) or  apt install jq  (Linux)
JOB=$(curl -s -X POST https://api.makistry.ai/v1/text-to-cad \
  -H "Authorization: Bearer mk_pub_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A 40x20x10mm rectangular box with a 5mm through-hole centered on the top face",
    "output_format": "STEP"
  }' | jq -r '.job_id')

echo "Job ID: $JOB"

Python

import httpx

API_KEY = "mk_pub_YOUR_KEY"
BASE = "https://api.makistry.ai/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

resp = httpx.post(f"{BASE}/text-to-cad", headers=headers, json={
    "prompt": "A 40x20x10mm rectangular box with a 5mm through-hole centered on the top face",
    "output_format": "STEP",
})
resp.raise_for_status()
job_id = resp.json()["job_id"]
print(f"Job ID: {job_id}")

Node.js

const API_KEY = "mk_pub_YOUR_KEY";
const BASE = "https://api.makistry.ai/v1";

const resp = await fetch(`${BASE}/text-to-cad`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    prompt: "A 40x20x10mm rectangular box with a 5mm through-hole centered on the top face",
    output_format: "STEP",
  }),
});
const { job_id } = await resp.json();
console.log("Job ID:", job_id);

Step 3 — Poll and download

The examples below poll every 10 seconds for simplicity. For production use, ramp to 15 s after the first 30 s — see async-jobs.md for the recommended approach.

curl

while true; do
  STATUS=$(curl -s "https://api.makistry.ai/v1/jobs/$JOB" \
    -H "Authorization: Bearer mk_pub_YOUR_KEY")
  STATE=$(echo $STATUS | jq -r '.status')
  echo "Status: $STATE"
  if [ "$STATE" = "success" ]; then
    URL=$(echo $STATUS | jq -r '.download_url')
    curl -L "$URL" -o output.step
    echo "Saved to output.step"
    break
  elif [ "$STATE" = "failed" ]; then
    echo "Failed: $(echo $STATUS | jq -r '.error_code'): $(echo $STATUS | jq -r '.error_message')"
    break
  fi
  sleep 10
done

Python

import time

def poll_job(job_id: str) -> dict:
    for _ in range(60):  # up to ~10 minutes
        resp = httpx.get(f"{BASE}/jobs/{job_id}", headers=headers)
        resp.raise_for_status()
        job = resp.json()
        status = job["status"]
        print(f"Status: {status}")
        if status == "success":
            return job
        if status == "failed":
            raise RuntimeError(f"{job['error_code']}: {job['error_message']}")
        time.sleep(10)
    raise TimeoutError("Job did not complete in time")

job = poll_job(job_id)
download_url = job["download_url"]

# Download the file
file_resp = httpx.get(download_url)
with open("output.step", "wb") as f:
    f.write(file_resp.content)
print("Saved to output.step")

Node.js

import fs from "fs/promises";

async function pollJob(jobId) {
  for (let i = 0; i < 60; i++) {
    const resp = await fetch(`${BASE}/jobs/${jobId}`, {
      headers: { "Authorization": `Bearer ${API_KEY}` },
    });
    const job = await resp.json();
    console.log("Status:", job.status);
    if (job.status === "success") return job;
    if (job.status === "failed") throw new Error(`${job.error_code}: ${job.error_message}`);
    await new Promise(r => setTimeout(r, 10_000));
  }
  throw new Error("Timeout");
}

const job = await pollJob(job_id);
const file = await fetch(job.download_url);
const buffer = await file.arrayBuffer();
await fs.writeFile("output.step", Buffer.from(buffer));
console.log("Saved to output.step");

Next Steps