
このIdeogram 4.6 APIガイドでは、APIキーの取得からcURLとPythonでの画像の完成までを案内し、続いてPoYoのスキーマが受け付けるすべての入力モードを取り上げます。プリセットまたはカスタムサイズでのテキストから画像、透過背景、通常の編集、マスク編集、参照画像、高精度編集です。テキストから画像にはモデルIDideogram-v4.6、編集にはideogram-v4.6-editを使います。どちらもIdeogram 4.6のモデルページに掲載されています。
フィールドのルールはPoYo APIリファレンスに基づいています。モデルの概要や他モデルとの比較については、まずIdeogram 4.6 APIの概要をご覧ください。
ステップ1:cURLでIdeogram 4.6 APIリクエストを送信する
PoYoダッシュボードでキーを作成し、POYO_API_KEYとしてエクスポートします。キーはブラウザのコードではなく、サーバー側に保管してください。
curl https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ideogram-v4.6",
"input": {
"prompt": "A colorful storefront with a neon sign reading \"HELLO\""
}
}'
これはデフォルト値(size: auto(約2K)、quality: medium、画像1枚)を使うため、料金は12 credits($0.06)です。送信に成功するとcode: 200と、task_id、status: "not_started"、created_timeを含むdataオブジェクトが返ります。これはキューに入ったタスクであり、画像ではありません。ボディ内のcodeは毎回確認してください。一部のバリデーションエラーはHTTP 200でcode: 400を返します。
ステップ2:タスクのステータスをポーリングする
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
ステータスはnot_started、runningと進み、最後にfinishedまたはfailedになります。完了したタスクではdata.filesに画像ごとに1件のエントリがあり、それぞれfile_urlとfile_type: "image"を持ち、課金額はcredits_amountに記載されます。失敗したタスクはerror_messageに理由が示されます。
ステップ3:上限付きのPythonポーリングループ
このループはHTTPステータスとボディのcodeの両方を確認し、failedで停止し、nが1より大きい場合はすべての画像を返し、再送信せずに10分で打ち切ります。
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
body = response.json()
if response.status_code >= 400 or body.get("code") != 200:
error = body.get("error") or {}
raise RuntimeError(f"PoYo error {body.get('code')}: {error.get('message', body)}")
return body["data"]
def run(model, input_body, max_wait=600):
task = checked(session.post(BASE + "/api/generate/submit",
json={"model": model, "input": input_body},
timeout=60))
task_id = task["task_id"]
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
time.sleep(5)
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
images = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
return images, task.get("credits_amount")
raise TimeoutError("Still running, check this task later: " + task_id)
images, credits = run("ideogram-v4.6", {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "1728x2304",
"quality": "high",
"n": 2,
})
print(images, credits)
1728x2304は3,981,312ピクセルの3:4サイズで、4,194,304ピクセルの境界を下回るため、2枚の画像は2Kのhigh料金で課金されます:2 × 20 = 40 credits($0.20)。タイムアウトは「同じタスクIDを後で再確認する」という意味です。再送信すると、課金対象の2つ目のタスクが始まってしまいます。同じrun()は編集にも使えます。モデルとして"ideogram-v4.6-edit"を渡してください。
Ideogram 4.6 APIのすべての入力モード
すべてのフィールドはinputの中に入れます。モデルIDと任意のcallback_urlはトップレベルに置きます。
4Kでのテキストから画像
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "2048x3072",
"quality": "high",
"n": 2
}
}
2048x3072は6,291,456ピクセルで4,194,304を超えるため、4Kティアとなり、このサイズではvery_lowは使えません。
透過背景と固定シード
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A flat sticker of a smiling coffee cup",
"size": "1:1 HD",
"quality": "low",
"background": "transparent",
"seed": 42
}
}
transparentはアルファチャンネル付きの画像を返し、opaqueは単色の背景を強制します。同じ結果を再現するには、同じボディを同じseedで送信します。
通常の編集
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
通常の編集では、プロンプトに基づいて画像を再生成します。image_urlsは画像をちょうど1枚含む配列で、公開HTTP(S) URLまたはbase64データURIで指定します。ローカルファイルを送る場合は、先にPoYoのファイルアップロードエンドポイントでアップロードしてください。
参照画像でスタイルを変更する
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Restyle the product shot to match the reference",
"image_urls": [
"https://example.com/product.png"
],
"reference_image_urls": [
"https://example.com/style.png"
],
"size": "2048x2048",
"quality": "low",
"n": 2
}
}
参照画像は最大4枚、マスク使用時は3枚まで指定できます。これはマスクなしの通常の編集なので、カスタムsizeを指定できます。
画像全体の高精度編集
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change only the date line to \"JULY 3-5 · RIVERSIDE PARK\". Keep everything else exactly the same.",
"image_urls": [
"https://example.com/poster.png"
],
"edit_precision": "high",
"context_window": "none",
"size": "auto",
"quality": "high"
}
}
これはローンチ当日の編集(タスク672JRU198S22NS8D、2026年11月20日)のボディで、ソースURLだけを差し替えています。ソースは2304×3072のポスターで、出力はそのサイズを保ったまま日付の行だけが変更され、タスクの課金額は4Kのhigh編集料金である120 credits($0.60)でした。
局所的なマスク編集
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change the sign text to \"OPEN LATE\"",
"image_urls": [
"https://example.com/storefront.png"
],
"mask_url": "https://example.com/sign-mask.png",
"edit_precision": "high",
"context_window": "auto",
"quality": "high"
}
}
マスクはソースと同じ寸法で、黒(編集)と白(保持)の両方の領域を含む必要があります。context_window: autoでは、マスク周辺の領域だけがソースの解像度で編集されます。マスクが大きすぎる場合は、画像全体の編集にフォールバックします。
フィールドのバリデーションルール
不正なリクエストがすぐに失敗するよう、送信前に自分の側で検証してください。
| フィールド | ルール |
|---|---|
model | ideogram-v4.6またはideogram-v4.6-edit |
prompt | 必須、1〜10,000文字、空白のみは不可 |
size | auto、1:1、1:1 HD、4:3、3:4、16:9、9:16、または小文字のxを使ったWIDTHxHEIGHT |
| カスタムサイズ | 各辺256〜4096かつ32の倍数。アスペクト比は1:6〜6:1の範囲 |
quality | very_lowは出力が4,194,304ピクセル以下の場合のみ |
n | 1〜8の整数。文字列と真偽値は拒否されます |
image_urls | 編集のみ。画像をちょうど1枚含む配列 |
mask_url、edit_precision: high | size: auto(またはsizeなし)が必要 |
background | edit_precisionがhighの場合は拒否 |
context_window: auto | mask_urlとedit_precision: highが必要 |
| 未知のフィールド | unsupported fieldsエラーで拒否 |
例:2304x3072は通ります(両辺とも32の倍数)。1296x3168は、Ideogram 4.5では受け付けられていましたが、1296が32の倍数ではないため失敗します。4096x512は失敗します(比率8:1)。2048x3072でのvery_lowも失敗します。
対処すべきエラー
code | 意味 | 対処 |
|---|---|---|
| 400 | パラメータが無効 | ボディを修正する。変更せずに再試行しない |
| 401 | APIキーがない、または無効 | Authorization: Bearerヘッダーを確認する |
| 402 | クレジット不足 | チャージしてから再送信する |
| 429 | レート制限超過 | 間隔を空けて後で再試行する |
| 500, 502, 503 | サーバー、上流、または可用性のエラー | バックオフ付きで再試行する。その前にタスクIDがすでに返っていないか確認する |
failedになったタスクは、error_messageに理由が含まれます。全一覧はError Codesをご覧ください。
ポーリングの代わりにコールバックを使う
ボディのトップレベル(inputの中ではありません)に"callback_url": "https://your-app.example.com/poyo-webhook"を追加します。タスクが完了または失敗すると、PoYoはタスクデータをそのURLにPOSTし、X-Webhook-SignatureヘッダーでHMAC-SHA256の署名を付けます。署名のルールはWebhookドキュメントに記載されています。届かないコールバックに備えて、低頻度のポーリングをフォールバックとして残しておいてください。
最初の請求額の計算方法
Ideogram 4.6 APIは出力画像ごとに課金されます:品質とサイズのティアの料金 × n。1 credit = $0.005です。
| リクエスト | ティア | 課金額 |
|---|---|---|
デフォルト(auto、medium、n: 1) | テキストから画像 medium 2K | 12 credits ($0.06) |
very_low、3:4、n: 1 | テキストから画像 very_low 2K | 1.6 credits ($0.008) |
high、1728x2304、n: 2 | テキストから画像 high 2K | 40 credits ($0.20) |
high、2304x3072、n: 1 | テキストから画像 high 4K | 40 credits ($0.20) |
2304×3072のソースの高精度編集、high | 編集 high 4K | 120 credits ($0.60) |
very_lowと2304x3072の行は、ローンチ当日のタスクで実際に課金された額と一致します。size: autoの編集では、料金はソース画像のサイズから見積もられ、納品された画像に基づいて確定しますが、見積額を超えることはありません。料金の記事に、さらに多くの計算例があります。
よくある質問
Ideogram 4.6 APIはOpenAI SDKと互換性がありますか?
いいえ。非同期タスクAPIです。/api/generate/submitに送信し、/api/generate/status/{task_id}をポーリングするか、コールバックを受け取ります。素のrequests、fetch、cURLで動作します。
Ideogram 4.6 APIで画像を編集するには?
image_urlsにURLを1つ入れ、変更内容をpromptに書いてideogram-v4.6-editを呼び出します。変更を指示していないピクセルを保持するには、edit_precision: highを追加します。
ideogram-v4.6に参照画像を送れますか?
いいえ。PoYoでは、参照画像はideogram-v4.6-editのreference_image_urlsに入れます。最大4枚、マスク使用時は3枚までです。
Ideogram 4.6 APIの1回のリクエストで何枚の画像が返りますか?
1〜8枚で、nで指定します。各画像はティアの料金で課金されます。
Ideogram 4.6 APIのリクエストがサイズで拒否されたのはなぜですか?
カスタムサイズの各辺は256〜4096の32の倍数である必要があり、マスクや高精度編集にはsize: autoが必要です。