エフェクト生成 V1

Purpose

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

クレジット消費: 5 (1K)、7 (2K)、10 (4K)

Method and Path

POST /public/v1/generate/effect/v1

Authentication

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

必須ヘッダー:

Authorization: Bearer {your_api_key}

Request Fields

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

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

背景色の値

値	ラベル	色
white	ホワイト	#FFFFFF
chroma_green	クロマキーグリーン	#52FF60
magenta	マゼンタ	#FF4CFF
light_gray	ライトグレー	#A6A6A6
light_purple	ライトパープル	#866CFE
dark_gray	ダークグレー	#6A6A6A

Response

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

{
  "job_id": "uuid-string"
}

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

Error / Validation Rules

状況	HTTP状態	エラーメッセージ
画像が有効な PNG または JPEG ファイルでない	400	"Invalid image file"
無効な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/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a glowing fantasy aura" \
-F "resolution=1K" \
-F "background_color=white"

cURL (画像あり):

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