Creovox API

빠른 시작

1. 01

   API 키 만들기

   로그인한 뒤 대시보드에서 API Keys를 엽니다. 앱마다 별도 키를 만들어 두면 하나를 비활성화해도 나머지는 그대로 동작합니다.

2. 02

   크레딧 구매

   API는 구매한 크레딧만 사용합니다. 무료 크레딧과 보너스 크레딧은 웹사이트에서는 계속 쓸 수 있지만 API로는 사용할 수 없습니다.

3. 03

   작업 생성 후 폴링

   프롬프트를 POST로 /api/v1/tasks에 보내고 task_id를 보관합니다. 그런 다음 상태가 succeeded 또는 failed가 될 때까지 몇 초마다 GET /api/v1/tasks/를 호출합니다.

인증

모든 요청의 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도 몇 분간 유효하면 됩니다.
• 작업은 비공개입니다. 키는 자기가 만든 작업만 읽을 수 있습니다.

자주 묻는 질문