エフェクト生成 V2

Purpose

テキストの説明と選択したフレーム数からエフェクトスプライトシートを非同期で生成します。任意で参照画像をアップロードでき、シートの背景色を選択できます。ウェブアプリの「エフェクト生成」ページの V2 タブ（デフォルトタブ）と同じ機能です。

クレジット消費: 3

Method and Path

POST /public/v1/generate/effect/v2

Authentication

認証ページを参照してください。Bearerトークンが必要です。

必須ヘッダー:

Authorization: Bearer {your_api_key}

Request Fields

リクエストは multipart/form-data で送信します。

フィールド名	タイプ	必須	説明
description	string	はい	エフェクトの説明。先頭と末尾の空白は削除されます
frame	integer	はい	フレーム。許可される値: 4, 9, 16
background_color	string	はい	シートの背景色。許可される値: white, chroma_green, magenta, light_gray, light_purple, dark_gray
image	file	いいえ	任意の参考画像 (PNG または JPEG)

背景色の表はエフェクト生成 V1を参照してください。

Response

成功レスポンス (200 OK):

{
  "job_id": "uuid-string"
}

フィールド	タイプ	説明
job_id	string	作成されたジョブの一意識別子。Get Job Statusで結果を照会します

Error / Validation Rules

状況	HTTP状態	エラーメッセージ
画像が有効な PNG または JPEG ファイルでない	400	"Invalid image file"
frame値が許可された値でない	400	"frame should be one of 4, 9, 16"
無効なAPIキー	401	"Invalid API key"
フィールド欠落または未知の enum 値	422	Validation error

Async Job Behavior

このエンドポイントは非同期ジョブを作成します。リクエスト即座にjob_idを返し、実際のエフェクト生成はバックグラウンドで進行します。

ポーリング方法:

1. レスポンスで受け取ったjob_idを保存します
2. GET /public/v1/job/{job_id}をポーリングして状態を確認します
3. 状態がSucceedになるとimage_urlsで結果を確認します

状態フロー: Pending → Succeed または Failed

Example Request

cURL (画像なし):

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/effect/v2" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a glowing fantasy aura" \
-F "frame=9" \
-F "background_color=white"

cURL (画像あり):

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/effect/v2" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a neon cyberpunk effect" \
-F "frame=16" \
-F "background_color=magenta" \
-F "image=@/path/to/input.png"