Creovox API

快速开始

1. 01

   创建 API 密钥

   登录后在控制台打开 API Keys。为每个应用单独创建密钥，这样停用其中一个不会影响其他应用。

2. 02

   购买积分

   API 只消耗购买的积分。免费积分和赠送积分仍可在网站上使用，但无法通过 API 使用。

3. 03

   创建任务并轮询

   用 POST 把提示词发到 /api/v1/tasks，记下 task_id，然后每隔几秒 GET /api/v1/tasks/，直到状态为 succeeded 或 failed。

身份验证

在每个请求的 Authorization 头中发送你的密钥。密钥与你的 Creovox 账户绑定；在其他站点创建的密钥会被拒绝。切勿把密钥写进浏览器代码或公开仓库。

Authorization: Bearer YOUR_API_KEY

端点

创建任务

把模型 id 放在 model 中，把参数放在 input 中。未知的参数名会被拒绝，拼写错误会直接报错。请发送 Idempotency-Key 请求头，这样重试的请求不会创建或计费第二个任务。

curl -X POST https://creovox.ai/api/v1/tasks \
  -H "Authorization: Bearer $CREOVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234-fox" \
  -d '{
    "model": "gpt-image-2.6",
    "input": {
      "prompt": "A red fox in fresh snow, cinematic light",
      "variant": "flare",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n42…gptimg",
    "model": "gpt-image-2.6",
    "status": "processing",
    "output": null,
    "credits_charged": 20,
    "refund_pending": false,
    "error": null,
    "created_at": "2026-11-07T08:00:00.000Z"
  }
}

GPT Image 2.6 参数

轮询结果

每 3 到 5 秒轮询一次，状态变为 succeeded 或 failed 时停止。图像通常需要几秒到几分钟；如果任务在 10 分钟后仍处于 processing，请停止轮询并带上 task_id 联系支持。任务成功后，output.images 中包含图像 URL；如需长期保存，请自行下载。

curl https://creovox.ai/api/v1/tasks/TASK_ID \
  -H "Authorization: Bearer $CREOVOX_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n42…gptimg",
    "model": "gpt-image-2.6",
    "status": "succeeded",
    "output": { "images": [{ "url": "https://…/image.png" }] },
    "credits_charged": 20,
    "refund_pending": false,
    "error": null,
    "created_at": "2026-11-07T08:00:00.000Z"
  }
}

任务状态

processing

任务正在处理，或正在等待扣费及供应商接受结果的确认。

succeeded

已完成。output.images 包含结果，credits_charged 为最终值。

failed

生成失败，error.message 会说明原因。已扣除的积分会自动退还：退款到账前 refund_pending 为 true，到账后 credits_charged 显示 0。你可以停止轮询。

// Node.js 18+
const API = 'https://creovox.ai/api/v1'
const headers = {
  Authorization: `Bearer ${process.env.CREOVOX_API_KEY}`,
  'Content-Type': 'application/json',
}

async function call(path, init = {}) {
  const res = await fetch(API + path, { ...init, headers: { ...headers, ...init.headers }, signal: AbortSignal.timeout(30_000) })
  const body = await res.json().catch(() => ({ code: res.status, message: res.statusText }))
  if (body.code !== 200) {
    const error = new Error(body.message)
    Object.assign(error, { status: res.status, type: body.error_type, data: body.data, retryAfter: res.headers.get('retry-after') })
    throw error
  }
  return body.data
}

// Reuse the same key when you retry this request: you get the same task and pay once.
const idempotencyKey = crypto.randomUUID()
let task
try {
  task = await call('/tasks', {
    method: 'POST',
    headers: { 'Idempotency-Key': idempotencyKey },
    body: JSON.stringify({ model: 'gpt-image-2.6', input: { prompt: 'A red fox in fresh snow' } }),
  })
} catch (error) {
  if (!error.data?.task_id || !['billing_unconfirmed', 'submission_unconfirmed'].includes(error.type)) throw error
  task = { task_id: error.data.task_id, status: 'processing' }
}

const deadline = Date.now() + 10 * 60_000
while (task.status === 'processing') {
  if (Date.now() > deadline) throw new Error(`Task ${task.task_id} is still processing; contact support.`)
  await new Promise(resolve => setTimeout(resolve, 4000))
  try {
    task = await call(`/tasks/${task.task_id}`)
  } catch (error) {
    // 429 and 5xx are temporary: wait and poll again. Anything else is final.
    if (error.status !== 429 && error.status < 500) throw error
    await new Promise(resolve => setTimeout(resolve, (Number(error.retryAfter) || 5) * 1000))
  }
}
console.log(task.status, task.output?.images, task.error, task.refund_pending)

价格

价格以积分计，与网站完全一致。1 积分等于 US$0.01。每张参考图像会额外收取少量积分。GET /api/v1/models 始终返回当前价格表。

错误

错误使用 HTTP 状态码和相同的 JSON 结构：code、message、error_type 和 data。

限制与建议

• 每个密钥都有每分钟请求上限和运行中任务上限。付费方案的上限更高。
• 每次创建请求都发送 Idempotency-Key 请求头。如果请求超时，请用同一个 Idempotency-Key 重试：你会得到同一个任务，也不会被重复计费。
• 参考图像必须能从公网访问。签名 URL 只要在几分钟内有效即可。
• 任务是私有的。一个密钥只能读取它自己创建的任务。

常见问题