API 参考
通过 REST API 将 ConceptViz 图表生成集成到您的应用中
认证
所有 API 请求需要通过 Authorization 请求头传入 API 密钥。
Authorization: Bearer cvk_your_api_key_here您可以在 设置 > API 密钥 页面创建和管理 API 密钥。
ConceptViz
通过 REST API 将 ConceptViz 图表生成集成到您的应用中
所有 API 请求需要通过 Authorization 请求头传入 API 密钥。
Authorization: Bearer cvk_your_api_key_here您可以在 设置 > API 密钥 页面创建和管理 API 密钥。
API 密钥拥有您账户积分的完整访问权限，请妥善保管，切勿在客户端代码中暴露。
https://conceptviz.app/api/v1图表生成是异步的。您提交请求后会收到一个任务 ID，然后轮询获取结果。
POST /api/v1/generate
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt | string | 是* | 描述图表的文本提示词 |
prompts | string[] | 是* | 批量生成的提示词数组（最多 4 个） |
quality | string | 否 | 图片分辨率："2k"（默认）或 "4k" |
aspectRatio | string | 否 | 宽高比（如 "16:9"、"1:1"） |
prompt（单个）和 prompts（批量）二选一。如果同时提供，prompts 优先。
{
"taskId": "vaW29_MJ1wbnyFU4bl_pd",
"status": "pending",
"credits_used": 1,
"credits_remaining": 79,
"poll_url": "/api/v1/task/vaW29_MJ1wbnyFU4bl_pd"
}GET /api/v1/task/{taskId}
每 3–5 秒轮询一次，直到 status 为 completed 或 failed。通常需要 30–90 秒完成生成。
{
"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"
}| 分辨率 | 每张图片消耗积分 |
|---|---|
2k | 1 |
4k | 2 |
积分在提交任务时扣除。如果生成失败，积分会自动退还。
# 第一步：提交
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",
"quality": "2k"
}')
TASK_ID=$(echo $RESPONSE | jq -r '.taskId')
echo
import requests
import time
API_KEY = "cvk_your_api_key_here"
BASE_URL = "https://conceptviz.app/api/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
const API_KEY = "cvk_your_api_key_here";
const BASE_URL = "https://conceptviz.app/api/v1";
// 第一步：提交
const submitResponse = await fetch(`${BASE_URL}/generate`, {
method: "POST",
API 返回标准 HTTP 状态码和 JSON 错误信息：
{
"error": "错误描述信息",
"code": "ERROR_CODE"
}| HTTP 状态码 | 错误码 | 说明 |
|---|---|---|
400 | INVALID_BODY | 请求体不是有效的 JSON |
400 | PROMPT_REQUIRED | 未提供 prompt 或 prompts |
400 | TOO_MANY_PROMPTS | 一次请求超过 4 个提示词 |
401 | UNAUTHORIZED | 缺少或无效的 Authorization 请求头 |
401 | INVALID_API_KEY | API 密钥无效或已禁用 |
402 | INSUFFICIENT_CREDITS | 积分不足（响应中包含 credits_remaining） |
403 | PLAN_LIMIT_EXCEEDED | 批量数量超出计划限制 |
404 | TASK_NOT_FOUND | 任务 ID 不存在或不属于您的账户 |
500 | GENERATION_FAILED | 图片生成失败（积分自动退还） |
response = requests.post(f"{BASE_URL}/generate", headers=headers, json=payload)
if response.status_code == 402:
data = response.json()
| 约束 | 值 |
|---|---|
| 每次请求最多图片数 | 4 |
| 每个账户最多 API 密钥数 | 5 |
| 生成耗时 | 通常 30–90 秒 |
| 推荐轮询间隔 | 3–5 秒 |
| 可用分辨率 | 2k、4k |