how-tos

Ideogram 4.6 APIガイド:cURLとPythonで最初の画像生成と編集

Poyo.ai Team
4 min read
Share:

cURLとPythonで使うIdeogram 4.6 APIガイド

この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では、マスク周辺の領域だけがソースの解像度で編集されます。マスクが大きすぎる場合は、画像全体の編集にフォールバックします。

フィールドのバリデーションルール

不正なリクエストがすぐに失敗するよう、送信前に自分の側で検証してください。

フィールドルール
modelideogram-v4.6またはideogram-v4.6-edit
prompt必須、1〜10,000文字、空白のみは不可
sizeauto、1:1、1:1 HD、4:3、3:4、16:9、9:16、または小文字のxを使ったWIDTHxHEIGHT
カスタムサイズ各辺256〜4096かつ32の倍数。アスペクト比は1:6〜6:1の範囲
qualityvery_lowは出力が4,194,304ピクセル以下の場合のみ
n1〜8の整数。文字列と真偽値は拒否されます
image_urls編集のみ。画像をちょうど1枚含む配列
mask_url、edit_precision: highsize: auto(またはsizeなし)が必要
backgroundedit_precisionがhighの場合は拒否
context_window: automask_urlとedit_precision: highが必要
未知のフィールドunsupported fieldsエラーで拒否

例:2304x3072は通ります(両辺とも32の倍数)。1296x3168は、Ideogram 4.5では受け付けられていましたが、1296が32の倍数ではないため失敗します。4096x512は失敗します(比率8:1)。2048x3072でのvery_lowも失敗します。

対処すべきエラー

code意味対処
400パラメータが無効ボディを修正する。変更せずに再試行しない
401APIキーがない、または無効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 2K12 credits ($0.06)
very_low、3:4、n: 1テキストから画像 very_low 2K1.6 credits ($0.008)
high、1728x2304、n: 2テキストから画像 high 2K40 credits ($0.20)
high、2304x3072、n: 1テキストから画像 high 4K40 credits ($0.20)
2304×3072のソースの高精度編集、high編集 high 4K120 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が必要です。

Share: