Creovox API

クイックスタート

1. 01

   API キーを作成する

   サインインしてダッシュボードの API Keys を開きます。アプリごとに別のキーを作成すると、1 つを無効化しても他に影響しません。

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 ヘッダーを付けると、再送しても 2 つ目のタスクを作成したり課金したりしません。

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。参照画像 1 枚ごとに少額が加算されます。GET /api/v1/models は常に最新の価格表を返します。

エラー

エラーは HTTP ステータスコードと同じ JSON 構造（code、message、error_type、data）を使います。

制限と推奨事項

• 各キーには 1 分あたりの制限と実行中タスクの制限があります。有料プランは制限が高くなります。
• 作成リクエストには必ず Idempotency-Key ヘッダーを付けます。リクエストがタイムアウトしたら、同じ Idempotency-Key で再送してください。同じタスクが返り、二重に課金されることはありません。
• 参照画像はパブリックインターネットから取得できる必要があります。署名付き URL も、数分間有効であれば使えます。
• タスクは非公開です。キーは自分が作成したタスクだけを読めます。

よくある質問