画像 API ガイド
POST /v1/images/generations でプロンプトから画像を生成します。参照素材に対応するモデルとマッピングでは、アップロードした file_id も利用できます。通常は直接結果を返し、動画のようなタスクポーリングは使いません。
モデルと生成設定
画像 API マッピングを持つ公共モデルを選び、YOUR_MODEL_ID を置き換えます。INONEAPI_API_KEY はサーバーの環境変数に保存します。
| パラメーター | 指針 |
|---|---|
model、prompt | 必須。被写体、構図、スタイル、文字、制約を記載。 |
n | 任意の枚数。まず 1 で確認。一部モデルは 1 枚のみ。 |
size | モデルが対応する寸法。ゲートウェイのリサイズ指示ではありません。 |
quality | モデル固有の値。他モデルの列挙値を混用しません。 |
output_format、background | 対応する場合のみ指定。透過には PNG/WebP などが必要。 |
response_format | 選択可能なプロバイダーのみ url、b64_json に対応。共通の必須項目ではありません。 |
最小リクエストから始め、確認済みのパラメーターを追加します。
プロンプトから生成
cURL またはサーバー上の Node.js 20+ を使用します。フロントエンドにキーを埋め込まないでください。
curl https://api.inoneapi.com/v1/images/generations \
-H "Authorization: Bearer $INONEAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL_ID","prompt":"A clean product photo of a white ceramic cup on a gray background","n":1}'結果の取得と保存
成功レスポンスには通常 created と data[] があり、各要素に b64_json または url、任意で revised_prompt を含みます。usage がなくても無料とは限りません。
Base64 は data URL 接頭辞を含まない画像バイト列です。例は実形式を確認する前に PNG/JPEG と誤認しないよう .bin に保存します。output_format や実際の内容を確認して対応する拡張子を使ってください。名前の変更は変換ではありません。
URL は通常一時的なので早めに自分のストレージへ保存します。ダウンロード時に InOneAPI キーを付けず、宛先、サイズ、タイムアウトを検証します。ブラウザーでは直接リンクを残し、CORS 対応を前提にしません。常に n 枚返るとは限らないため各要素を確認します。
{
"created": 1789430400,
"data": [
{
"url": "https://example.com/generated-image.png"
}
]
}参照画像
先に画像をアップロードし、生成にも同じキーを使用します。以下は参照画像に明示的に対応するマッピング向けです。
{
"model": "YOUR_MODEL_ID",
"prompt": "Keep the reference composition and use a white background.",
"input_references": [
{
"type": "image",
"role": "reference",
"source": {
"type": "file",
"file_id": "file_ioa_0123456789abcdef0123456789abcdef"
}
}
]
}input_references は InOneAPI 拡張です。所有権と image 型を検証し、source を COS 署名 URL に変換して role を保持した後にマッピングします。任意の画像編集が自動的に可能になるわけではありません。役割や枚数はモデル依存です。ファイルは ready かつ実体が必要です。保存は 1 日ライフサイクル、署名 URL は 5 分なので、非同期読み取りは両方が有効な間に必要です。
ストリーミングと制約
ネイティブ対応時のみ stream: true を使い、プロバイダーの SSE を解析します。partial_images は対応モデルに限ります。途中画像イベントは追加の最終画像ではなく、SSE 全体を JSON 配列として扱えません。
request DSL が必要なリクエストはストリーミング変換できません。共通の画像タスク照会、variations、自動非同期ポーリングはありません。ファイル参照で編集 API が追加されるわけでもありません。画像を理解して文章を得る場合は画像入力対応のテキスト API を使います。
エラーと運用
400 は寸法・品質・形式・役割・対応能力、401/403 はキーとモデル権限、429 は Retry-After と並行数を確認します。502 は上流や正規化の失敗の場合があります。HTTP エラー時は data[0] を読む前に処理してください。
タイムアウト時も生成・課金が完了している場合があります。適切な期限を設定し、無制限に再送しません。Base64 は本文サイズとメモリを増やし、DSL の既定バッファー上限は 32 MiB です。枚数、解像度、並行数を制限し、X-Gateway-Trace-ID を記録します。