画像生成エンドポイント

共通の取り決め（ベースアドレス、認証、レスポンス構造、レート制限）は認証と基本仕様を参照してください。

画像の作成

POST/v1/images/generations

認証方式

Authorization: Bearer <API_KEY>。コンソールの「API キー」で作成したプラットフォーム API Key を使用します。

リクエストボディ · application/json

Prop

Type

画像モデルはサイズ、枚数、返却形式の制限がそれぞれ異なります。まず /v1/models で確認し、エンドポイントが返すパラメータ検証エラーに従ってください。

リクエスト例

まず /v1/models で現在の Key で利用可能な画像モデル ID を確認し、model をそれに置き換えてください。 size はそのモデルがサポートする段階値の範囲内である必要があります。モデルによって最小ピクセル数が大きく異なり、誤って指定するとサイレントにダウングレードされるのではなく、直接パラメータエラーが返ります。

レスポンスはアドレス形式の場合も Base64 形式の場合もあり、モデルとチャネルによって異なります。

リクエスト

curl -X POST "https://locopalai.com/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的图片模型 ID",
  "prompt": "白色桌面上的一个红苹果，柔和自然光，产品摄影",
  "size": "当前模型支持的尺寸",
  "n": 1
}
JSON

レスポンスパラメータ

パラメータ	型	説明
`created`	integer	生成時刻（Unix 秒）
`model`	string	一部のモデルは実際に実行されたモデル ID を返す
`data`	array	生成結果一覧
`data[].url`	string	画像アドレス。URL 形式で返される場合に存在し、短期の署名付きアドレスの可能性がある
`data[].b64_json`	string	Base64 の画像データ。Base64 形式で返される場合に存在する
`data[].size`	string	一部のモデルは実際の生成サイズを返す
`size`	string	トップレベルで実際の生成サイズを返す（例：`1024x1024`、`1376x768`）
`quality`	string	トップレベルで実際の画質段階を返す（例：`auto`、`low`）
`output_format`	string	トップレベルで実際の出力形式を返す（例：`png`）
`background`	string	トップレベルで背景の処理方法を返す（例：`auto`、`opaque`）
`moderation`	string	トップレベルでコンテンツ審査の段階を返す。一部のモデルのみ
`usage`	object	画像の使用量。画像から画像への生成では入力画像の token が追加で計上される

1 回のリクエストで url のみ、または b64_json のみが返る場合があり、モデルとチャネルによって異なります。実際に返されたフィールドに従い、両方が存在する場合は url を優先してください。

レスポンスボディ

アドレスを返す（url 形式）：

{
  "created": 1789567052,
  "data": [
    {
      "size": "2048x2048",
      "url": "https://media.example.com/image-public-id.jpeg"
    }
  ],
  "model": "Doubao-Seedream-4.5"
}

Base64 を返す（b64_json 形式、抜粋）：

{
  "background": "auto",
  "created": 1789071752,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU..." }
  ]
}

url 形式で返されるアドレスは短期の署名付きアドレスの可能性があるため、速やかに転存または登録してください。b64_json 形式は自身でデコードし、適切に保管してください。すべての画像モデルが response_format や同じサイズを受け付けると仮定しないでください。実測では gpt-image-1-mini は response_format を拒否し、Doubao-Seedream-4.5 は現在、画像が少なくとも 3686400 ピクセルであることを要求し、2048x2048 は受理されますが 1024x1024 はパラメータエラーを返します。

エラーレスポンス

{
  "error": {
    "message": "当前图片模型不支持请求的尺寸",
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "param": "size"
  }
}

HTTP	レスポンス / 原因	対応
`400`	`Model name not specified, model name cannot be empty`	リクエストボディに `model` がない
`400`	`invalid_parameter`（`param=size`）	現在のモデルがサポートするサイズに変更する
`400`	`unknown_parameter`（`param=response_format`）	このフィールドを削除し、モデルのデフォルトの返却形式を使用する
`400`	`InvalidParameter` / `upstream_error`	上流モデルがサイズ、ピクセル数などのパラメータを拒否。`message` に従って調整する
`400`	`invalid_parameter`（`param=n`）	`n=1` に変更する
`400`	`image is required`（`code=convert_request_failed`）	画像から画像への生成リクエストに参照画像が含まれていない。下の例に従って `image` を補う
`400`	`n must be an integer between 1 and 128`（`code=invalid_request`）	`n` が範囲外。`1`–`128` に変更する
`429`	`credit_balance_exhausted` / `insufficient_quota`	現在のチャネルの残高が不足。他の利用可能なチャネルに変更するか、プラットフォームサポートに連絡する
`401`	`Invalid token`	API Key の欠落、誤り、失効
`500`	`{"error":{"code":"convert_request_failed","message":"not supported model for image generation, only imagen models are supported"}}`	現在のモデルが画像生成エンドポイントをサポートしていない。このエンドポイントをサポートする画像モデルに変更する
`503`	`model_not_found` / `No available channel`	現在のグループにこのモデルの利用可能なチャネルがない。同種のモデルに変更する

完全な説明はエラーコードとトラブルシューティングを参照してください。

画像から画像（画像編集）

POST/v1/images/edits

既存の画像をもとに新しい画像を生成します。1 枚または複数の参照画像をアップロードすると、モデルが prompt に従って画面を書き換え、スタイルを変更し、または部分的な再描画を行います。

リクエストボディ · multipart/form-data

Prop

Type

リクエストには必ず参照画像を含める必要があります。欠けている場合はエンドポイントが直接パラメータエラーを返し、モデルには到達しません。

リクエスト例

画像から画像への生成は multipart/form-data を使用し、-F でフィールドごとに送信してください。-d は使用しないでください。参照画像は image=@文件路径 でアップロードします。

複数の参照画像が必要な場合は、フィールドを配列形式 image[] にして繰り返してください。ここには JSON リクエストボディはなく、Content-Type は curl -F が自動的に設定するため、手書きしないでください。

画像から画像

curl -X POST "https://locopalai.com/v1/images/edits" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -F "model=从 /v1/models 选择的图片模型 ID" \
  -F "prompt=把这张照片改成柔和的水彩画风格" \
  -F "size=1024x1024" \
  -F "image=@./reference.png"

複数の参照画像の場合はこのフィールドを繰り返します：

  -F "image[]=@./reference-a.png" \
  -F "image[]=@./reference-b.png"

レスポンスボディ

画像の作成と同じ構造で、画像は b64_json または url で返されます：

{
  "background": "opaque",
  "created": 1789651524,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU..." }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 1041,
    "input_tokens_details": { "image_tokens": 1032, "text_tokens": 9 },
    "output_tokens": 439,
    "total_tokens": 1480
  }
}

usage.input_tokens_details.image_tokens は参照画像の消費を反映します。参照画像が多いほど、またはサイズが大きいほど、入力 token が増えます。

公開アドレスで参照画像を渡す

参照画像入力に対応するモデルは、POST /v1/images/generations の JSON リクエストボディで images を使用して渡すこともできます。要素は公開 https:// の画像アドレスです：

curl -X POST "https://locopalai.com/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的图片模型 ID",
  "prompt": "把这张照片改成柔和的水彩画风格",
  "images": ["https://example.com/reference.png"]
}
JSON

参照画像はサーバー側から直接ダウンロードできる必要があります。アドレスが失効している場合やログインが必要な場合、リクエストは上流のダウンロードエラーで終了します。レスポンス構造は画像の作成と同一です。

素材ライブラリとの関係

画像生成の結果が自動的に素材ライブラリに入ることはありません。以降の動画タスクで画像を参照画像として使用する場合は、まず素材ライブラリのエンドポイントで登録し、Active になるまでポーリングしてから、asset://<asset_id> で参照してください。

このページの目次