API Reference

Authorization: Bearer cvk_your_api_key_here

https://conceptviz.app/api/v1

{
  "taskId": "vaW29_MJ1wbnyFU4bl_pd",
  "status": "pending",
  "model": "cv-2",
  "quality": "2k",
  "aspect_ratio": "16:9",
  "credits_used": 2,
  "credits_remaining": 79,
  "poll_url": "/api/v1/task/vaW29_MJ1wbnyFU4bl_pd"
}

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

{
  "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-2"
  }'

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-2"

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-2",
  "quality": "2k",
  "aspect_ratio": "16:9",
  "credits_used": 2,
  "credits_remaining": 79,
  "poll_url": "/api/v1/task/vaW29_MJ1wbnyFU4bl_pd"
}

# 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-2",
    "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-2",
        "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-2",
    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 != 200:
    print(f"Error: {response.json()['error']}")
else:
    data = response.json()
    task_id = data["taskId"]
    # Start polling...