APIVN API で画像を生成

API に接続

サイトの API URL に Content-Type: application/json と Authorization: Bearer YOUR_API_KEY を付けて送信します。x-api-key も利用できます。

API key はサーバー側で管理してください。例では環境変数を使用し、代理でリクエストを送信することはありません。

read -r -s -p "STALI_API_KEY: " STALI_API_KEY
export STALI_API_KEY
printf '\n'
curl -fsS https://apivn.dev/v1/models -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}"

画像モデルを選択

req/gpt-image-2 または req/gemini-3.0-pro-image を使用します。model を省略するか空にすると、どちらの画像エンドポイントも req/gpt-image-2 を使用します。

GET /v1/models で現在のモデル一覧と pricing.per_request を確認できます。API key に選択したモデルの使用権限が必要です。

プロンプトから生成

model と画像の説明 prompt を含む POST リクエストを /v1/images/generations に送信します。例では n: 1、size: 1024x1024 を指定します。 処理が完了すると JSON が返ります。stream は false に固定され、SSE ストリームは返りません。

cURL の例は macOS、Linux、WSL の Bash 用です。Python では pip install requests でライブラリをインストールしてください。Node.js は 18 以降を使い、コードを .mjs ファイルに保存して組み込みの fetch を使用します。

curl --fail-with-body --dump-header image-response-headers.txt "https://apivn.dev/v1/images/generations" \
  -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "req/gpt-image-2",
  "prompt": "A small botanical robot tending a seedling, studio product photography, soft natural light, clean ivory background, no text",
  "n": 1,
  "size": "1024x1024"
}'

参照画像を編集

/v1/images/edits に JSON 形式で POST し、空でない prompt と image を指定します。画像には data URL、base64 文字列、公開 http(s) URL を使用できます。cURL では https://example.com/reference.png を実際に公開アクセスできる画像 URL に置き換えてください。Python または Node.js では、実行するディレクトリに reference.png を置いてください。

image の別名として image_url、reference_image、ref_image、refImage も使えます。値は文字列または {url: ...} オブジェクトで指定し、画像フィールドは 1 つだけ送信してください。 編集エンドポイントは JSON を受け付け、multipart/form-data には対応しません。画像 URL は公開アクセス可能で、認証情報を含まないものにしてください。内部アドレスはブロックされます。 参照画像は PNG、JPEG、WebP、GIF に対応します。 SDK の images.edit が multipart/form-data を送信する場合、そのまま使用しないでください。このエンドポイントは JSON を要求します。Python requests と Node.js fetch の例は対応する形式です。

curl --fail-with-body --dump-header image-response-headers.txt "https://apivn.dev/v1/images/edits" \
  -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "req/gpt-image-2",
  "prompt": "Keep the subject and composition, change the background to a warm ivory studio",
  "image": "https://example.com/reference.png",
  "n": 1,
  "size": "1024x1024"
}'

パラメータと制限

JSON リクエスト全体の上限は、エンコードされた画像を含めて 20 MiB です。Base64 はデータサイズを増やします。Playground の制限は別途適用されます。

返された画像を読み取り保存

JSON 応答の data 配列を読み取ります。画像はプロバイダーに応じて b64_json、b64Json、url に含まれます。追加フィールドはモデルごとに異なる場合があります。

{
  "data": [
    {
      "b64_json": "<base64 image bytes>"
    }
  ]
}

base64 は画像ファイルにデコードするか、実際の形式に合った MIME タイプで data URL を作成します。すべての出力が PNG とは限りません。 URL は画像のダウンロードや表示に使えます。有効期間やアクセス条件はプロバイダーによって異なります。

調査用に x-apivn-request-id を保存してください。成功応答のヘッダーには x-apivn-model、x-apivn-price-vnd-per-request、x-apivn-cost-vnd も含まれます。

リクエスト単位の料金

画像モデルは request 単位で課金されます。実行前に GET /v1/models の pricing.per_request を確認してください。残高や API key の利用上限により要求が拒否される場合があります。 応答やヘッダーのトークン数は、画像モデルの料金を再計算する基準ではありません。新たなリクエストには別の料金が発生する場合があります。

タイムアウトや切断後に自動再送しないでください。前の要求が処理済みの可能性があります。再度呼び出す前に Usage の履歴を確認し、照合やサポートへの問い合わせに備えて request ID を保存してください。

エラーを慎重に処理

ゲートウェイのエラー形式は {type: "error", error: {type, message, ...}} です。HTTP ステータスと error.message を確認し、取得できる場合は request ID を保存してください。

リクエスト送信前

API key、モデル権限、現在の料金を確認してください。正しいエンドポイントへ JSON を送り、小さなデータと画像 1 枚から始めます。base64 と URL の両方に対応し、request ID を保存して結果を確認してから再呼び出しを判断してください。

1. API key とモデルの権限を確認します。
2. /v1/models でモデルと料金を確認します。
3. JSON、prompt、画像データを確認します。
4. base64 と URL の両方に対応します。
5. Usage の履歴を確認し、照合やサポート用に request ID を保存します。