HiAPI
Ja
ブログ

チュートリアル

HiAPI API で muse-image-1.0/text-to-image を呼び出す方法：curl と Python

Nov 3, 2026
米色纸层沿对角逐层退远的抽象几何封面图，石墨色层边与一张陶土色纸片点缀，为 HiAPI 教程文章配图。

この統合で実際に必要なもの

HiAPI では、テキストから画像への呼び出しは 1 回の同期 HTTP リクエストです。生成したい画像を記述した JSON リクエストボディを送信すると、レスポンスには生成された画像データが含まれて返されます。このエンドポイントにはポーリングループやジョブキューを管理する必要はありません。1 回のリクエスト、1 回のレスポンスです。

関与するコンポーネントはわずかです。

  • あなたの API キー — Authorization ヘッダーでリクエストを認証します。
  • エンドポイント — HiAPI のベース URL 上にある muse-image-1.0/text-to-image の固定 URL パス。
  • JSON リクエストボディ — プロンプトと、モデルが受け付ける任意のパラメータを運びます。
  • レスポンスペイロード — 生成された画像データを返し、あなたがデコードまたは転送します。

インターフェースはこれだけです。以下のセクションでは、curl でリクエストを段階的に組み立て、次に Python で同じプロセスを繰り返します。これにより、複雑さを増す前に各部分を検証できます。

前提条件と認証

最初のリクエストを送る前に、以下を用意してください。

  1. API キー — HiAPI アカウントのダッシュボードから取得します。パスワードと同じように扱い、ソースコード管理にコミットしないでください。
  2. HTTP クライアント — テストには curl で十分です。スクリプト版の対象環境は Python 3.8 以上です。
  3. HiAPI API のベース URL — ダッシュボードのドキュメントでキーと一緒に確認できます。

認証には Authorization ヘッダーの Bearer トークンを使用します。muse-image-1.0/text-to-image へのすべてのリクエストに必要です。

Authorization: Bearer $HIAPI_API_KEY

キーはスクリプト内にハードコードせず、環境変数に保存してください。

export HIAPI_API_KEY="your-key-here"

このモデルのエンドポイントパスはベース URL に続く /muse-image-1.0/text-to-image です。正確なベース URL は HiAPI ダッシュボードに記載されています。コードを変更せずに環境を切り替えられるよう、こちらも環境変数に保存してください。

export HIAPI_BASE_URL="https://api.hiapi.ai"   # confirm the current value in your dashboard

この 2 つの変数を設定すれば、リクエストを送信する準備が整います。

動作する curl リクエスト

以下は最小限の muse-image-1.0/text-to-image 呼び出しです。プロンプトを送信し、生の JSON レスポンスをファイルに書き込みます。これにより、解析コードを書く前にレスポンスを確認できます。

curl -sS -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a quiet harbor at dawn, soft fog, wide angle",
    "n": 1
  }' \
  -o response.json

リクエストボディについて注意すべき点がいくつかあります。

  • prompt は必須です。モデルがレンダリングするテキスト記述です。
  • n は任意で、リクエストする画像の数を制御します。省略するとデフォルト値が使用されます。
  • HiAPI API リファレンスでこのモデルについて確認済みのパラメータのみを含めてください。ドキュメント化されていないフィールドを推測しないでください。未知のパラメータはサーバー側の検証で拒否されるか、暗黙的に無視される可能性があります。

リクエストが成功すると、response.json に画像データが含まれます。失敗した場合は、エラーレスポンスボディと 2xx 以外のステータスコードが返されます。以下のエラー処理セクションを参照してください。

レスポンスボディ全体を出力せずに HTTP ステータスコードだけを確認できます。

curl -sS -o /dev/null -w "%{http_code}\n" -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"test"}'

同じリクエストを Python で実装する

Python 版では requests を使用し、curl 呼び出しと完全に同じ処理を行います。同じエンドポイント、同じヘッダー、同じリクエストボディです。再利用可能な関数として切り出しましょう。

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

def generate_image(prompt: str, n: int = 1) -> dict:
    url = f"{BASE_URL}/muse-image-1.0/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {"prompt": prompt, "n": n}

    response = requests.post(url, headers=headers, json=payload, timeout=60)
    response.raise_for_status()  # raise on 4xx/5xx
    return response.json()

if __name__ == "__main__":
    result = generate_image("a quiet harbor at dawn, soft fog, wide angle")
    print(result.keys())

残しておくべき 2 つのポイントがあります。

  • timeout=60 — 明示的なタイムアウトを設定します。画像生成は一般的な JSON API 呼び出しよりも遅いため、タイムアウトがないと、接続が停止した際にプロセスが無期限にハングする可能性があります。
  • raise_for_status() — HTTP エラーを例外として表面化します。エラーレスポンスボディを画像として黙って解析することを防ぎます。

すでに httpx や aiohttp を使用している場合、変換は簡単です。同じヘッダー、同じ JSON リクエストボディです。このリクエストは特定の HTTP ライブラリに依存しません。

同期レスポンスを読み取る

muse-image-1.0/text-to-image は同期であるため、画像データは同じレスポンス内で届きます。結果を取得するための 2 回目の呼び出しは不要です。レスポンスは JSON です。パーサーを書く前に、一度その構造を確認しましょう。

import json

result = generate_image("a quiet harbor at dawn")
print(json.dumps(result, indent=2)[:500])

画像の扱いはレスポンスに含まれる内容によって決まります。

レスポンスに base64 画像データが含まれる場合

文字列をデコードし、バイトをファイルに書き込みます。

import base64

b64 = result["data"][0]["b64_json"]   # field name: confirm against the API reference
with open("output.png", "wb") as f:
    f.write(base64.b64decode(b64))

レスポンスに URL が含まれる場合

通常の GET でダウンロードします。この URL は取得用に認可されているため、API キーをサードパーティのホストに付加しないでください。

import requests

image_url = result["data"][0]["url"]   # field name: confirm against the API reference
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
    f.write(img.content)

正確なフィールド名 — b64_json と url、およびそれらを包む外側の構造 — は、このモデルの HiAPI API リファレンスで定義されています。まずレスポンスを一度出力して構造を確認し、それに基づいてコードを書きましょう。異なるモデルの構造を仮定しないでください。

サービス内では、ローカルディスクに無闇に書き込まないでください。バイトをオブジェクトストレージにストリーミングするか、画像を消費する場所（アップロードステップ、キュー、自身のクライアントへのレスポンス）に直接渡します。転送する前に、デコードされたバイトが画像らしいこと（マジックバイトの確認）を検証してください。

エラーコードとリトライの処理

HiAPI は標準的な HTTP ステータスコードを返します。有用なトリアージのルールは次のとおりです。リクエストを変更せずに再度送信した場合、同じリクエストは成功するか？

リクエストを修正する — リトライしない

  • 400 Bad Request — 不正な JSON、またはモデルが受け付けないパラメータ。prompt が存在するか、存在しないフィールドを作っていないかを確認してください。リクエストボディを修正しましょう。そのままリトライしても同様に失敗します。
  • 401 Unauthorized — API キーが欠落しているか無効です。HIAPI_API_KEY が設定されていて、ローテーションされていないことを確認してください。
  • 403 Forbidden — キーは有効ですが、このエンドポイントへのアクセス権がありません。ダッシュボードでアカウントのアクセス権を確認してください。
  • 404 Not Found — パスが間違っています。エンドポイント文字列が正確に /muse-image-1.0/text-to-image であり、ベース URL が正しいことを確認してください。
  • 422 Unprocessable Entity — JSON は整形式ですが意味的に無効です。たとえば値が範囲外です。エラーメッセージを読みましょう。通常はフィールド名が示されます。

バックオフ付きでリトライする

  • 429 Too Many Requests — レート制限中です。指数バックオフでリトライしてください。Retry-After ヘッダーが存在する場合はそれに従ってください。
  • 5xx エラー — サーバー側の障害です。指数バックオフと上限（例：3 回の試行）を設定してリトライし、その後は諦めてエラーを表面化させてください。

コンパクトなリトライループ。

import time

def post_with_retry(url, headers, payload, attempts=3):
    for i in range(attempts):
        resp = requests.post(url, headers=headers, json=payload, timeout=60)
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(2 ** i)
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError(f"failed after {attempts} attempts: {resp.status_code} {resp.text}")

失敗時は常にステータスコードとエラーレスポンスボディをログに記録してください。レスポンスボディのメッセージは、そのエラーが 2 つのカテゴリのどちらに属するかを教えてくれます。

公開前の本番チェックリスト

いくつかの習慣により、muse-image-1.0/text-to-image 呼び出しはノート PC を離れた後も予測可能になります。

  • リクエスト構造を固定する。 JSON リクエストボディを API リファレンスに記載されたフィールドで検証してください。パラメータを追加する場合は、まずサポートされていることを確認しましょう。
  • すべての箇所でタイムアウトを設定する。 生成呼び出しと、返された画像データのダウンロードには明示的なタイムアウトが必要です。
  • エラーのカテゴリを区別する。 リトライ可能な失敗（429、5xx）と終端的な失敗（400、401、403、404、422）を分けることで、アラートが煩雑にならず、リトライも無駄になりません。
  • 重要な情報を記録する。 レスポンスがリクエスト ID を提供する場合は、それとステータスコード、レイテンシ、プロンプトの長さを記録してください。プロンプトに機密テキストが含まれる可能性がある場合は、プロンプト自体を記録しないでください。
  • コストの要因に注意する。 生成は出力に対して課金されます。画像の数、サイズ、リトライの頻度がコストに影響します。終端的なエラーをリトライしないようにし、キャッシュが有効な場合は再生成を避けましょう。
  • キーはサーバー側に保持する。 ブラウザやモバイルクライアントに API キーを埋め込んでエンドポイントを直接呼び出さないでください。

これで、統合はどこからでも呼び出せる小さく退屈な関数になります。まさにそれが望ましい姿です。完全なパラメータの範囲と現在のレスポンスフィールドについては、このモデルの HiAPI API リファレンスを参照してください。

関連記事

すべての記事を見る →

永続的なAIアーティファクトで開発を始める

APIキーを取得して、タスクベースの1つのAPIで画像・動画・音声モデルを呼び出せます。

APIドキュメントを読む