AICU Image API
α版。1つのキー・1つのエンドポイントで GPT-Image-2 と Nano Banana 2（Gemini）を切り替えられます。
リファレンスを読む前に、何ができるか見てください
以下はリファレンスです。先に動いているところを見たい場合、次の 3 枚はいずれも
このページの curl 1 本ずつで出てきたものです。
6 人のキャラクターを 1 枚に、それぞれの造形を保ったまま。難しいのは 6 人描くことではなく、 互いに混ざらないようにすることです。
4 コマ漫画をリクエスト 1 本で。 4 コマとも同じキャラクターで、コマ割りも あとから合成したのではなくモデルが行っています。
9 ポーズのスプライトシートを単色背景で。 そのまま切り出してゲームや VTuber の素材にできます。
解説記事
引くためではなく読むために書いてあります。下のリファレンスが重いと感じたらこちらから。
| 何が分かるか | |
|---|---|
| GPT-Image-2.5 — API マニュアル翻訳 | 全パラメータと、それぞれが実際に何を変えるか |
| プロンプトガイド 日本語訳 | このモデル向けのプロンプトの書き方＋バッチ生成サンプル |
| 画像生成ガイド Part 1 | API の選び方・マルチターン編集・ストリーミング |
| 自社キャラクターで試した記録 | 上の 3 枚と、それを出した実際のプロンプト |
| AiCutyBench — 本当に再現できるのか | 繰り返し生成したときの歩留まりの実測（うまくいった 1 枚ではなく） |
Base URL
https://api.aicu.ai/v1
認証
API キー（images scope）が必要です。ダッシュボードで発行してください。
Authorization: Bearer aicu_live_xxx
GET /v1/images/models
利用可能な画像モデル（認証不要）。
curl https://api.aicu.ai/v1/images/models
| model | 提供元 | 参照画像 | アスペクト比 | 特徴 |
|---|---|---|---|---|
gpt-image-2 | OpenAI | ○ | - | 高品質・キャラクター一貫性 |
nano-banana | Gemini | ○ | ○ | 高速・アスペクト比指定 |
sd3.5-large | Stability | - | - | Stable Diffusion 3.5 Large |
移行元のモデル名（gemini-3.1-flash-image-preview など）もそのまま受け付けます。
POST /v1/images/generations
curl -X POST https://api.aicu.ai/v1/images/generations \
-H "Authorization: Bearer aicu_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "nano-banana",
"prompt": "a red apple on a white table, product photo",
"aspect_ratio": "16:9"
}'
リクエスト
| パラメータ | 型 | 説明 |
|---|---|---|
prompt | string | 必須。生成内容 |
model | string | 既定 gpt-image-2 |
aspect_ratio | string | 16:9 等（nano-banana のみ） |
size | string | 1024x1024 / 1536x1024 等 |
quality | string | low / medium / high |
reference_image | string | 参照画像の base64（data URL 可） |
character | string | 参照画像プリセット。指定すると model より優先 |
seed | number | 再現用（sd3.5-large） |
force | boolean | true でキャッシュを無視して再生成 |
レスポンス
OpenAI 互換の形で返ります。
{
"data": [{ "b64_json": "iVBORw0KG..." }],
"cached": false
}
同じ条件の再生成は R2 キャッシュから返り、キャッシュヒットは無料です（cached: true）。
⏱ gpt-image-2 は 100秒を超えることがある — タイムアウトしても生成は失敗していません
gpt-image-2 の生成は実測 113〜171秒かかることがあります。100秒を超えると素朴な HTTP クライアントは接続が切れて「失敗した」ように見えますが、生成は裏で完了しており、課金も1回分だけです。タイムアウトを理由に再試行しないでください（1回あたり数千 AP が無駄になります）。
取り戻す経路（3つ）:
GET /v1/images/recent— 直近の生成物を id 付きで一覧し、GET /v1/images/file/{id}で本体を取得- ダッシュボードの利用履歴
- キーの所有者にはメールでも届きます（件名
[AICU API] An image exceeded the request timeoutに PNG 添付）
最初から防ぐには:
"stream": trueを渡す — SSE で部分画像が流れ続けるため接続が切れません（※character/reference_image/maskとは併用不可。素の生成のみ）"notify_email"（+"app_name"）を渡す — アプリのエンドユーザーに直接、完成通知を送れます- 同期で受けるなら、クライアントのタイムアウトを 240秒以上に（curl は
--max-time 240、requests はtimeout=240）
参照画像でキャラクターを保つ
方法1: 登録済みキャラクタープリセット（character） — AiCuty 公式キャラクターは登録済みで、参照画像の準備なしで一貫した見た目の生成ができます。
# 一覧（認証不要）: slug・モデル・単価・権利表記が返ります
curl https://api.aicu.ai/v1/images/characters
# 使う: character に slug を渡すだけ（大文字小文字は区別しません）
curl -X POST https://api.aicu.ai/v1/images/generations \
-H "Authorization: Bearer aicu_live_xxx" \
-H "Content-Type: application/json" \
-d '{"character": "SakiNoir", "prompt": "カフェで読書している、午後の光"}'
登録済みプリセット（参照画像つき・gpt-image-2）: SakiNoir / NaoVerde / MeiSoleil / ElenaBloom / MinaAzure / elec_sheep ほか。一覧 API の rights にクレジット表記・権利者が含まれるので、公開時はそれに従ってください。
方法2: 自分の参照画像（reference_image） — R2 への事前登録は不要です。手元の画像を base64 で渡してください。
import base64, requests
ref = base64.b64encode(open("character.png", "rb").read()).decode()
res = requests.post(
"https://api.aicu.ai/v1/images/generations",
headers={"Authorization": "Bearer aicu_live_xxx"},
json={
"model": "nano-banana",
"prompt": "Using the reference image as a character guide, draw the same character waving hello",
"reference_image": ref,
"aspect_ratio": "16:9",
},
timeout=180,
)
open("out.png", "wb").write(base64.b64decode(res.json()["data"][0]["b64_json"]))
移行ガイド: OpenAI / Gemini から差し替える
Gemini (google-genai) からの移行
- client = genai.Client(api_key=GEMINI_API_KEY)
- response = client.models.generate_content(
- model="gemini-3.1-flash-image-preview",
- contents=prompt,
- config=types.GenerateContentConfig(
- response_modalities=["IMAGE", "TEXT"],
- image_config=types.ImageConfig(aspect_ratio="16:9"),
- ),
- )
+ res = requests.post(
+ "https://api.aicu.ai/v1/images/generations",
+ headers={"Authorization": f"Bearer {AICU_API_KEY}"},
+ json={"model": "nano-banana", "prompt": prompt, "aspect_ratio": "16:9"},
+ )
OpenAI SDK からの移行
- client = OpenAI(api_key=OPENAI_API_KEY)
- res = client.images.generate(model="gpt-image-2", prompt=prompt, size="1024x1024")
+ res = requests.post(
+ "https://api.aicu.ai/v1/images/generations",
+ headers={"Authorization": f"Bearer {AICU_API_KEY}"},
+ json={"model": "gpt-image-2", "prompt": prompt, "size": "1024x1024"},
+ )
差し替えると、プロバイダごとのキー管理が不要になり、利用量・コストがダッシュボードに集約されます。
エラー
| ステータス | 意味 |
|---|---|
| 401 | API キーが無効 |
| 403 | キーに images scope が無い |
| 402 | クレジット不足 |
| 404 | 未知のモデル |
| 503 | プロバイダのキー未設定 / 生成失敗 |
利用量の確認
curl https://api.aicu.ai/v1/usage -H "Authorization: Bearer aicu_live_xxx"
ダッシュボードの利用履歴では「画像」でフィルタできます。
Support
- Dashboard: https://api.aicu.ai/dashboard
- Contact: https://aicu.ai/contact
© 2026 AICU Inc.