grok-imagine-quality テキスト生成画像 API の使い方：curl、Python、そして一度で実行できるリクエスト

概要

• これは何か：hiapi 上で grok-imagine-quality/text-to-image API を使う実行可能な方法——POST /v1/tasks でタスクを作成し、GET /v1/tasks/<taskId> をポーリング（またはコールバックを使用）し、output[0].url から画像をダウンロードします。
• schema は厳格かつ簡潔：prompt（必須）、aspect_ratio（13 種類の比率、デフォルト 1:1）、resolution（1k | 2k、小文字、デフォルト 1k）、output_format（jpeg | png | webp、デフォルト jpeg）。それ以外のフィールドはすべて 400 で拒否されます。
• 「Quality」はグレードであり、調整項目ではありません。quality や rich_detail といったパラメータは存在しません——より豊かなディテール、マテリアル、ライティングはこのモデルバリアントがデフォルトで提供するものです。安価なバルク下書きが必要な場合は、同じエンドポイントに標準グレードの姉妹モデル grok-imagine/text-to-image があります。
• 出力 URL には expireAt の期限があります——速やかにダウンロードするか、永続ストレージに保存してください。

何を構築するか、そして何を準備するか

目標：grok-imagine-quality/text-to-image にテキストプロンプトを送信し、メインビジュアルとして使える完成画像ファイルを取得する——まず curl で、次にタスクキューに組み込める小さな Python スクリプトで。

必要なものは 1 つだけ：hiapi API キーです。hiapi コンソール から取得してエクスポートします：

export HIAPI_API_KEY="sk-..."

すべてのリクエストは標準の bearer ヘッダーで認証します：Authorization: Bearer sk-<key>。

最小の実行可能なリクエスト（curl）

hiapi 上の画像生成は非同期のみです。長時間の HTTP 呼び出しを待つのではなく、タスクを作成し、完了後に結果を取得します。

ステップ 1——タスクを作成：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-quality/text-to-image",
    "input": {
      "prompt": "スレートのカウンターに置かれたマットブラックのエスプレッソマシンの製品メインビジュアル、ドラマチックな指向性ライティング、浅い被写界深度、ハイエンドなコマーシャル質感",
      "aspect_ratio": "16:9",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

モデルがバックグラウンドで処理している間、すぐに taskId が返ります：

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR" }
}

ステップ 2——終了状態になるまでポーリング：

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

タスクは queued → handling → archiving と進み、最終的に success または fail に到達します。success のみが出力を持ちます：

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "grok-imagine-quality/text-to-image",
    "status": "success",
    "created": 1783130400,
    "completed": 1783130460,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../image.png",
        "type": "image",
        "expireAt": 1783735260
      }
    ]
  }
}

ステップ 3——expireAt より前にダウンロード：

curl -o hero.png "https://cdn.hiapi.ai/tasks/.../image.png"

Python での同じフロー

完全なスクリプト——作成、ポーリング、保存。コピーして HIAPI_API_KEY を設定し、実行するだけです。

import os
import time

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

payload = {
    "model": "grok-imagine-quality/text-to-image",
    "input": {
        "prompt": (
            "スレートのカウンターに置かれたマットブラックのエスプレッソマシンの製品メインビジュアル、"
            "ドラマチックな指向性ライティング、浅い被写界深度、ハイエンドなコマーシャル質感"
        ),
        "aspect_ratio": "16:9",
        "resolution": "2k",       # 小文字！"2K" は 400 で拒否されます
        "output_format": "png",
    },
}

resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()  # ここでの 4xx = リクエスト自体が拒否された
course_id = resp.json()["data"]["taskId"]
print("タスクを作成しました:", task_id)

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        image = task["output"][0]
        with open("hero.png", "wb") as f:
            f.write(requests.get(image["url"], timeout=120).content)
        print("hero.png を保存しました")
        break
    if status == "fail":
        err = task["error"]
        raise RuntimeError(f"タスク失敗: {err['code']} {err['message']}")
    time.sleep(5)  # queued / handling / archiving —— ポーリングを続ける

2k グレードの生成は通常 1〜2 分で完了します。5 秒のポーリング間隔で十分です。

実際に存在するパラメータ

入力 schema は厳格です——未知のフィールドは黙って無視されるのではなく、400 INVALID_REQUEST: additional properties not allowed で失敗します。これは良い知らせです：タイプミスが本番環境に紛れ込むことはありません。インターフェースの全範囲：

フィールド	必須	値	デフォルト値
input.prompt	はい	自由テキスト	—
input.aspect_ratio	いいえ	2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2	1:1
input.resolution	いいえ	1k, 2k（小文字のみ）	1k
input.output_format	いいえ	jpeg, png, webp	jpeg

これを基に構築する前に知っておくべきことが 3 つあります：

• 名前の「quality」はグレードであり、パラメータではありません。このモデルはより豊かなディテール、マテリアル、ライティングを持つと説明されているのを目にするかもしれません——それはモデルバリアント自体です。切り替え可能な rich_detail、quality、style フィールドはありません。
• 1k と 2k は異なるグレードで課金されます。一般的なパターン：1k でプロンプトを繰り返し調整し、勝ち残ったプロンプトで 2k を再実行して最終素材を生成します。現在の画像 1 枚あたりの価格は hiapi 料金ページ を参照してください。
• n も seed も negative_prompt もありません。1 タスクで 1 枚の画像を生成します。バリエーションが必要な場合は複数のタスクを並行して送信してください——それらは互いに独立し、並行してキューに入ります。

本番環境での注意点：コールバック、冪等性、エラー

本番環境ではポーリングよりもコールバックを優先してください。リクエストボディのトップレベル（input の中ではない）に callback を渡すと、タスクが終了状態に到達したときに hiapi があなたのサービスを呼び出します：

{
  "model": "grok-imagine-quality/text-to-image",
  "input": { "prompt": "..." },
  "callback": {
    "url": "https://your-service.example.com/hiapi/callback",
    "when": "final"
  }
}

when: "final" を使うと success と fail の両方が通知されるため、あなたの側で taskId による重複排除を行ってください。コールバックが失われる可能性に備えて、低頻度のポーリングをフォールバックとして残してください——タスク詳細エンドポイントが常に信頼できる情報源です。

Idempotency-Key を使ってリトライを安全に。タスク作成は Idempotency-Key ヘッダー（最大 255 バイト）を受け付けます。同じ key でリトライしても重複タスクは絶対に作成されません——再生すると元の taskId が返ります：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Idempotency-Key: order-42-hero-image" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-quality/text-to-image", "input": {"prompt": "..."}}'

3 種類の失敗形態を区別して処理する：

1. 認証失敗——HTTP 401 および {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}。キーと、そのキーにこのモデルの使用権限があるかを確認してください。盲目的にリトライしないでください。
2. 無効な入力——HTTP 400 および "error_code": "INVALID_REQUEST"、メッセージは具体的なフィールドを指摘します（例：resolution: value must be one of '1k', '2k'）。payload を修正してください。同じリクエストボディでリトライしても同じように失敗します。
3. タスクレベルの失敗——作成呼び出しは成功したが、タスクが status: "fail" と data.error オブジェクトで終了する。再送信する前に error.code を確認してください。

expireAt に注意。出力 URL は一時的です。タスク成功後すぐにファイルをダウンロードするか、作成時に storage: "persistent" を渡して出力を長期保持してください。

関連ページ

• grok-imagine-quality/text-to-image モデルページ——プレイグラウンドとグレード別料金
• ドキュメントの完全なパラメータリファレンス
• タスク作成 API リファレンス——headers、冪等性、コールバック
• grok-imagine-quality の画像生成画像の使い方——同じグレードで、既存の画像を編集
• すべての画像、動画、音楽モデル

よくある質問

grok-imagine-quality と grok-imagine/text-to-image の違いは何ですか？ 同じエンドポイント、同じリクエスト構造、異なるグレードです。quality グレードはメインビジュアルやコマーシャル素材向けで、より豊かなディテールとライティングを持ち、1k/2k の解像度グレードで課金されます。標準版 grok-imagine/text-to-image はバルク処理やアイデア出し向けの、より高速で安価な選択肢です。

なぜ "resolution": "2K" は 400 を返すのですか？ 列挙値は大文字小文字を区別し、小文字です：1k または 2k。大文字の値は INVALID_REQUEST で拒否されます。

1920x1080 のような正確なピクセルサイズを設定できますか？ できません。aspect_ratio（2:1 の超ワイドから 9:20 の超トールまで 13 の選択肢）で形状を、1k/2k グレードで鮮明さを制御します。このモデルには自由形式の size フィールドはありません。

1 つのリクエストで複数の画像を生成できますか？ できません——n パラメータはありません。複数のタスクを並行して送信してください。各タスクは独自の taskId を返し、並行して処理されます。

grok-imagine-quality は画像生成画像をサポートしていますか？ はい、別のモデル id grok-imagine-quality/image-to-image を使用します。その schema は画像生成画像の方法を参照してください——テキスト生成画像とは異なります。

結果 URL の有効期間はどのくらいですか？ 各 output[] エントリには expireAt Unix タイムスタンプがあります。その期限前にダウンロードするか、タスク作成時に storage: "persistent" を使用して（または後で出力を昇格させて）保持してください。

キューに入ったが未完了のタスクはどのように見えますか？ GET /v1/tasks/<taskId> が返す status は queued、handling、または archiving で、まだ output はありません。success のみがダウンロード可能な出力を含み、fail は data.error を含みます。