> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Flux Images Generation API 連携説明
> Flux API guide - Ace Data Cloud
本稿では、カスタムパラメータを入力して Flux 公式の画像を生成できる Flux Images Generation API の連携説明を紹介します。
## 申請フロー
Flux Images Generation API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API Token を取得し、控えとして保管してください。
まだログインまたは登録していない場合は、自動的にログインページへ遷移して登録とログインを案内され、完了後は自動的に現在のページへ戻ります。
**1 つの API Token でプラットフォーム上のすべてのサービスを呼び出せるため、サービスごとに個別申請する必要はありません。** 初回申請時には無料クレジットが付与され、無料で体験できます。クレジットが不足した場合は [コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。
> 📘 完全なドキュメント：[Flux Images Generation API →](https://platform.acedata.cloud/documents/flux-images)
## 基本的な使用方法
まず基本的な使用方法を確認します。プロンプト `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」ボタンをクリックするとテストできます。ここでは以下の結果を取得しました。
```json theme={null}
{
"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 のコードは以下のとおりです。
```shell theme={null}
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：編集する必要がある画像をアップロードします。
入力例は以下のとおりです。
入力が完了すると、以下のコードが自動生成されます。
対応するコード：
```python theme={null}
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)
```
実行をクリックすると、直ちに以下の結果が得られることがわかります。
```json theme={null}
{
"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/](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` 上で生成された画像の結果を確認できます。図のとおりです。
内容は以下のとおりです。
```json theme={null}
{
"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`：内部サーバーエラー。サーバー側で問題が発生しました。
### エラー応答例
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## 結論
本ドキュメントを通じて、Flux Images Generation API を使用して、プロンプトを入力することで画像を生成する方法を理解しました。本ドキュメントが、この API との連携および利用に役立つことを願っています。ご不明な点がございましたら、いつでも弊社の技術サポートチームまでお問い合わせください。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.