Diagram Generation API Reference

Authorization: Bearer cvk_your_api_key_here

https://conceptviz.app/api/v1

{
  "taskId": "vaW29_MJ1wbnyFU4bl_pd",
  "status": "pending",
  "model": "cv-3-fine",
  "requested_model": "cv-2",
  "notice": "cv-2 is retired; requests now use cv-3-fine",
  "credits_used": 1
}

{
  "taskId": "vaW29_MJ1wbnyFU4bl_pd",
  "status": "pending",
  "model": "cv-3-fine",
  "mode": "standard",
  "quality": "2k",
  "aspect_ratio": "16:9",
  "credits_used": 1,
  "credits_remaining": 80,
  "poll_url": "/api/v1/task/vaW29_MJ1wbnyFU4bl_pd"
}

{
  "status": "completed",
  "images": [
    {
      "url": "https://conceptviz.app/images/abc123.png",
      "prompt": "water cycle diagram"
    }
  ],
  "generation_strength": "standard"
}

{
  "status": "failed",
  "error": "Image generation failed. Please try again later.",
  "code": "GENERATION_FAILED",
  "credits_refunded": true
}

{
  "status": "processing"
}

curl -X POST https://conceptviz.app/api/v1/edit \
  -H "Authorization: Bearer cvk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Replace the annotations with a clean professional architecture diagram",
    "images": ["https://example.com/marked-up-diagram.png"],
    "model": "cv-3-fine",
    "mode": "standard"
  }'

curl -X POST https://conceptviz.app/api/v1/edit \
  -H "Authorization: Bearer cvk_your_api_key_here" \
  -F "prompt=Convert this sketch into a polished system diagram" \
  -F "image=@./sketch.png" \
  -F "model=cv-3-fine"

curl -X POST https://conceptviz.app/api/v1/edit \
  -H "Authorization: Bearer cvk_your_api_key_here" \
  -F "prompt=Combine these references into one clean diagram" \
  -F "image=@./reference-1.png" \
  -F "image=@./reference-2.png"

{
  "taskId": "vaW29_MJ1wbnyFU4bl_pd",
  "status": "pending",
  "model": "cv-3-fine",
  "mode": "standard",
  "quality": "2k",
  "aspect_ratio": "16:9",
  "credits_used": 1,
  "credits_remaining": 80,
  "poll_url": "/api/v1/task/vaW29_MJ1wbnyFU4bl_pd"
}

curl -X POST https://conceptviz.app/api/v1/batch \
  -H "Authorization: Bearer cvk_your_api_key_here" \
  -H "Idempotency-Key: lesson-42-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": [
      "Water cycle for grade 5",
      "Photosynthesis inside a leaf",
      "Food chain in a pond"
    ],
    "style_reference_image": "https://conceptviz.app/images/abc123.png",
    "style": "Keep labels short and use a white background",
    "quality": "2k"
  }'

{
  "batch_id": "bat_k3Jv9...",
  "status": "pending",
  "model": "cv-3-fine",
  "mode": "standard",
  "quality": "2k",
  "aspect_ratio": "16:9",
  "total": 3,
  "credits_per_image": 1,
  "credits_used": 3,
  "credits_remaining": 77,
  "items": [
    { "index": 0, "task_id": "vaW29_MJ1wbnyFU4bl_pd" },
    { "index": 1, "task_id": "Qm3x..." },
    { "index": 2, "task_id": "p0Zc..." }
  ],
  "poll_url": "/api/v1/batch/bat_k3Jv9..."
}

{
  "batch_id": "bat_k3Jv9...",
  "status": "partial",
  "model": "cv-3-fine",
  "total": 3,
  "counts": { "pending": 0, "processing": 0, "completed": 2, "failed": 1 },
  "credits_used": 3,
  "credits_refunded": 1,
  "items": [
    {
      "index": 0,
      "task_id": "vaW29_MJ1wbnyFU4bl_pd",
      "status": "completed",
      "prompt": "Water cycle for grade 5",
      "images": [{ "url": "https://conceptviz.app/images/def456.png", "prompt": "Water cycle for grade 5" }]
    },
    {
      "index": 2,
      "task_id": "p0Zc...",
      "status": "failed",
      "prompt": "Food chain in a pond",
      "error": "Image generation failed. Please try again later.",
      "code": "GENERATION_FAILED",
      "credits_refunded": true
    }
  ]
}

# Start an Advanced SVG export, then poll until it is ready
EXPORT_ID=$(curl -s -X POST https://conceptviz.app/api/v1/export \
  -H "Authorization: Bearer cvk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "task_id": "vaW29_MJ1wbnyFU4bl_pd", "format": "svg" }' | jq -r '.export_id')

while true; do
  RESULT=$(curl -s https://conceptviz.app/api/v1/export/$EXPORT_ID \
    -H "Authorization: Bearer cvk_your_api_key_here")
  STATUS=$(echo $RESULT | jq -r '.status')
  [ "$STATUS" != "processing" ] && break
  sleep 10
done

curl -s https://conceptviz.app/api/v1/export/$EXPORT_ID/download \
  -H "Authorization: Bearer cvk_your_api_key_here" -o image.svg

# Step 1: Submit
RESPONSE=$(curl -s -X POST https://conceptviz.app/api/v1/generate \
  -H "Authorization: Bearer cvk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "water cycle diagram showing evaporation, condensation, and precipitation",
    "model": "cv-3-fine",
    "mode": "standard",
    "quality": "2k"
  }')

TASK_ID=$(echo $RESPONSE | jq -r '.taskId')
echo "Task ID: $TASK_ID"

# Step 2: Poll until complete
while true; do
  RESULT=$(curl -s https://conceptviz.app/api/v1/task/$TASK_ID \
    -H "Authorization: Bearer cvk_your_api_key_here")
  STATUS=$(echo $RESULT | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    echo $RESULT | jq .
    break
  fi
  sleep 5
done

import requests
import time

API_KEY = "cvk_your_api_key_here"
BASE_URL = "https://conceptviz.app/api/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# Step 1: Submit
response = requests.post(
    f"{BASE_URL}/generate",
    headers=HEADERS,
    json={
        "prompt": "photosynthesis process diagram",
        "model": "cv-3-fine",
        "mode": "standard",
        "quality": "2k",
    },
)

data = response.json()
task_id = data["taskId"]
print(f"Task submitted: {task_id}")
print(f"Credits used: {data['credits_used']}, remaining: {data['credits_remaining']}")

# Step 2: Poll for result
while True:
    result = requests.get(f"{BASE_URL}/task/{task_id}", headers=HEADERS).json()
    print(f"Status: {result['status']}")

    if result["status"] == "completed":
        for image in result["images"]:
            print(f"Image URL: {image['url']}")
        break
    elif result["status"] == "failed":
        print(f"Error: {result['error']}")
        print(f"Credits refunded: {result.get('credits_refunded', False)}")
        break

    time.sleep(5)

const API_KEY = "cvk_your_api_key_here";
const BASE_URL = "https://conceptviz.app/api/v1";

// Step 1: Submit
const submitResponse = await fetch(`${BASE_URL}/generate`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompts: [
      "cell division mitosis diagram",
      "DNA double helix structure",
    ],
    model: "cv-3-fine",
    mode: "standard",
    quality: "2k",
  }),
});

const { taskId, credits_used, credits_remaining } = await submitResponse.json();
console.log(`Task: ${taskId}, credits used: ${credits_used}`);

// Step 2: Poll for result
while (true) {
  const pollResponse = await fetch(`${BASE_URL}/task/${taskId}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const result = await pollResponse.json();
  console.log(`Status: ${result.status}`);

  if (result.status === "completed") {
    console.log("Images:", result.images);
    break;
  } else if (result.status === "failed") {
    console.error("Failed:", result.error);
    break;
  }

  await new Promise((r) => setTimeout(r, 5000));
}

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

response = requests.post(f"{BASE_URL}/generate", headers=headers, json=payload)

if response.status_code == 402:
    data = response.json()
    print(f"Not enough credits. Remaining: {data.get('credits_remaining', 0)}")
elif response.status_code == 429:
    wait = int(response.headers.get("Retry-After", "5"))
    print(f"{response.json()['code']}: retrying in {wait}s")
    time.sleep(wait)
elif response.status_code != 200:
    print(f"Error: {response.json()['error']}")
else:
    data = response.json()
    task_id = data["taskId"]
    # Start polling...