Flux Images Generation API 連携説明

Flux API guide - Ace Data Cloud

本稿では、カスタムパラメータを入力して Flux 公式の画像を生成できる Flux Images Generation API の連携説明を紹介します。

​

申請フロー

Flux Images Generation API を使用するには、まず Ace Data Cloud コンソール で API Token を取得し、控えとして保管してください。

まだログインまたは登録していない場合は、自動的にログインページへ遷移して登録とログインを案内され、完了後は自動的に現在のページへ戻ります。

1 つの API Token でプラットフォーム上のすべてのサービスを呼び出せるため、サービスごとに個別申請する必要はありません。 初回申請時には無料クレジットが付与され、無料で体験できます。クレジットが不足した場合は コンソール で共通残高をチャージできます。

📘 完全なドキュメント：Flux Images Generation API →

​

基本的な使用方法

まず基本的な使用方法を確認します。プロンプト prompt、生成アクション action、画像サイズ size を入力すると、処理後の結果を取得できます。まず action フィールドを簡単に渡す必要があり、その値は generate です。その後、プロンプトも入力する必要があります。具体的な内容は以下のとおりです。

ここでは Request Headers を設定していることがわかります。内容は以下のとおりです。

• accept：どの形式のレスポンス結果を受け取りたいかを指定します。ここでは application/json、つまり JSON 形式を指定します。
• authorization：API を呼び出すためのキーで、申請後に直接プルダウンから選択できます。

また、Request Body を設定しています。内容は以下のとおりです。

• action：今回の画像生成タスクのアクション。
• size：画像生成結果のサイズ。flux-2-flex / flux-2-pro / flux-2-max シリーズでは画像比率（例：1:1、16:9）を必ず渡す必要があり、1024x1024 のようなピクセルサイズは受け付けません。省略すると 400 が返されます。
• count：生成する画像の数。デフォルト値は 1 です。このパラメータは画像生成タスクでのみ有効であり、編集タスクでは無効です。
• prompt：プロンプト。
• model：生成モデル。デフォルトは flux-dev です。最新のフラッグシップは flux-2-pro、flux-2-max（より高画質で、画像比率 size と組み合わせる必要があります）です。
• callback_url：結果のコールバックを受け取る URL。
• async：オプション。true に設定すると、インターフェースは直ちに task_id を返します。callback_url を指定する必要はなく、その後、対応するタスク照会インターフェースを通じてポーリングし、結果を取得します。

パラメータ size にはいくつかの特別な制限があり、主に width x height の幅と高さの比率、x:y の画像比率という 2 種類に分かれます。具体的には以下のとおりです。

モデル	範囲
flux-dev	幅と高さの比率 1024x1024、1024x1792、1792x1024、または画像比率をサポート
flux-pro	幅と高さの比率 1024x1024、1024x1792、1792x1024、または画像比率をサポート
flux-2-flex	画像比率のみをサポート
flux-2-pro	画像比率のみをサポート
flux-2-max	画像比率のみをサポート
flux-kontext-pro	画像比率のみをサポート
flux-kontext-max	画像比率のみをサポート

参考となる画像比率： “21:9”, “16:9”, “4:3”, “3:2”, “1:1”, “2:3”, “3:4”, “9:16”, “9:21”。

パラメータを選択すると、右側に対応するコードが自動生成されます。コピーする前に、認証ヘッダーで自分の API Key を使用していることを確認してください。ドキュメントやスクリーンショットに実際の認証情報を表示してはいけません。

「Try」ボタンをクリックするとテストできます。ここでは以下の結果を取得しました。

{
  "success": true,
  "task_id": "5456c749-3bbb-4f10-9eb8-cfbcac297500",
  "trace_id": "ae4eecb8-1dd6-45b4-bfb3-a1c48872536e",
  "data": [
    {
      "image_url": "https://cdn.acedata.cloud/assets/examples/flux/5456c749-3bbb-4f10-9eb8-cfbcac297500-d0ef60485f73.jpg"
    }
  ]
}

返却結果には複数のフィールドがあり、以下のとおりです。

• success：この時点での動画生成タスクのステータス。
• task_id：この時点での動画生成タスク ID。
• trace_id：この時点での動画生成トラッキング ID。
• data：この時点での画像生成タスクの結果リスト。
  • image_url：この時点での画像生成タスクのリンク。
  • prompt：プロンプト。

満足のいく画像情報を取得できたことがわかります。結果内の data にある画像リンクアドレスに基づいて、生成された Flux 画像を取得するだけです。

また、対応する連携コードを生成したい場合は、直接コピーして生成できます。たとえば、CURL のコードは以下のとおりです。

curl -X POST 'https://api.acedata.cloud/flux/images' \
-H 'authorization: Bearer {token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "prompt": "A photorealistic studio product shot of a frosted-glass perfume bottle on wet black slate, single softbox key light, water droplets, dark moody background, 85mm macro.",
  "model": "flux-2-pro",
  "size": "1:1"
}'

​

画像編集タスク

ある画像を編集したい場合は、まずパラメータ image_url に編集する画像のリンクを渡す必要があります。この時、action は edit のみをサポートしており、以下の内容を指定できます。

• model：今回の画像編集タスクで使用するモデル。flux-dev、flux-pro、flux-kontext-pro、flux-kontext-max、flux-2-flex、flux-2-pro、flux-2-max をサポートします。
• image_url：編集する必要がある画像をアップロードします。

入力例は以下のとおりです。

入力が完了すると、以下のコードが自動生成されます。

対応するコード：

import requests

url = "https://api.acedata.cloud/flux/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "edit",
    "prompt": "a white siamese cat",
    "model": "flux-kontext-pro",
    "image_url": "https://cdn.acedata.cloud/ytj2qy.png"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

実行をクリックすると、直ちに以下の結果が得られることがわかります。

{
  "success": true,
  "task_id": "2a7979ff-1f77-4380-92c6-a2dc37c3b4c8",
  "trace_id": "732b65c0-48d9-49f7-b568-64e5acffe4c0",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
      "timings": 1752744073
    }
  ]
}

生成された効果は、元の画像を編集した効果であり、結果は上記と類似していることがわかります。

​

非同期コールバック

Flux Images Generation API は生成に比較的長い時間を要し、およそ 1～2 分かかります。API が長時間応答しない場合、HTTP リクエストは接続を維持し続け、追加のシステムリソースを消費することになります。そのため、本 API は非同期コールバックもサポートしています。

全体のフローは次のとおりです。クライアントがリクエストを開始する際に、追加で callback_url フィールドを指定します。クライアントが API リクエストを開始すると、API は直ちに結果を返します。結果には現在のタスク ID を表す task_id フィールド情報が含まれます。タスクが完了すると、生成された画像の結果は POST JSON の形式でクライアントが指定した callback_url に送信されます。その中にも task_id フィールドが含まれているため、タスク結果を ID によって関連付けることができます。

以下の例で、具体的な操作方法を確認します。

まず、Webhook コールバックは HTTP リクエストを受信できるサービスであり、開発者は自身で構築した HTTP サーバーの URL に置き換える必要があります。ここではデモを容易にするため、公開 Webhook サンプルサイト https://webhook.site/ を使用します。このサイトを開くと、図に示すように Webhook URL を取得できます。

この URL をコピーすれば、Webhook として使用できます。ここでのサンプルは https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab です。

次に、フィールド callback_url を上記の Webhook URL に設定し、同時に対応するパラメーターを入力します。具体的な内容は図のとおりです。

実行をクリックすると、次のように直ちに結果が得られることがわかります。

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

しばらく待つと、https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab 上で生成された画像の結果を確認できます。図のとおりです。

内容は以下のとおりです。

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
      "seed": 1698551532,
      "timings": {
        "inference": 3.328
      }
    }
  ]
}

結果には task_id フィールドがあり、その他のフィールドはすべて上記と類似していることがわかります。このフィールドによってタスクの関連付けを実現できます。

​

エラー処理

API を呼び出す際にエラーが発生した場合、API は対応するエラーコードと情報を返します。例：

• 400 token_mismatched：Bad request。パラメーターの欠落または無効が原因である可能性があります。
• 400 api_not_implemented：Bad request。パラメーターの欠落または無効が原因である可能性があります。
• 401 invalid_token：Unauthorized。認証トークンが無効または欠落しています。
• 429 too_many_requests：リクエストが多すぎます。レート制限を超えています。
• 500 api_error：内部サーバーエラー。サーバー側で問題が発生しました。

​

エラー応答例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

結論

本ドキュメントを通じて、Flux Images Generation API を使用して、プロンプトを入力することで画像を生成する方法を理解しました。本ドキュメントが、この API との連携および利用に役立つことを願っています。ご不明な点がございましたら、いつでも弊社の技術サポートチームまでお問い合わせください。