画像と動画のプロンプト拡張

· Hyperouter · 読了目安 4 分

画像モデルや動画モデルは、長く具体的なプロンプトをうまく扱えますが、実際には短いプロンプトを書く方がほとんどです。プロンプト拡張はその差を埋めます。"prompt_expand": true を指定すると、生成の前に Hyperouter がモデル向けにプロンプトを書き直します。画像ではより詳しい描写に、動画では秒ごとの台本になります。

既定ではオフのため、プロンプトは書いたとおりにモデルへ送られます。

対応するモデル

prompt_expand を列挙している Lumina と Qwen の画像モデル・動画モデルが対応しています。対応モデルは順次追加されるため、記事の記載ではなく一覧を確認してください。GET /v1/models は各モデルの supported_parameters を返し、このフィールドに対応するモデルはそこに prompt_expand を列挙します。

curl https://api.hyperouter.app/v1/models \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY"

このフィールドが使えるのは、画像または動画の作成だけです。それ以外のモデルや、動画の編集・延長・リミックスでは 400 unsupported_parameter で拒否されます。prompt_extend: true とは併用できず、400 invalid_body で拒否されます。

リクエストでオンにする

prompt_expand は、画像と動画の作成呼び出しのトップレベルのフィールドです。OpenAI SDK では、追加のボディフィールドとして送信します。Qwen Image 2.0 が対応しています。

curl https://api.hyperouter.app/v1/images/generations \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen-image-2.0",
    "prompt": "A lighthouse at dusk",
    "prompt_expand": true
  }'

動画では、同じフィールドを付けて POST /v1/videos を呼びます。もう 1 つのフィールド locale は、zh-CN のような BCP 47 タグです。prompt_expand と併用すると、動画のセリフを書く言語を指定でき、モデルはその言語で話します。指定しない場合、セリフは英語になります。

生成されたものを確認する

レスポンスには、モデルが受け取ったプロンプトである expanded_prompt が含まれます。お客様の prompt は変更されません。このフィールドは次の場所にあります。

Hyperouter は expanded_prompt をリクエストから 30 日間保持し、それを過ぎると null を返します。何も拡張されなかった場合も null です。

30 日より長く必要な場合は、expanded_prompt をご自身の記録に保存してください。

料金

書き直しは同じリクエストで課金され、使用したトークンに x-ai/grok-4.6 のトークン単価が適用されます。Hyperouter は、他のリクエストと同様に、書き直しにかかりうる最大額を生成分とあわせて事前に確保し、実際に使われた分を課金します。2 回目の呼び出しはありません。

書き直しが失敗した、タイムアウトした、または使えなかった場合でも、リクエスト自体は失敗しません。モデルは送信されたとおりのプロンプトで生成し、レスポンスは expanded_prompt: null となり、書き直しは無料です。

利用を申請する

プロンプト拡張は、Hyperouter がアカウントで有効にした後に使えます。申請するには、ダッシュボードでサポートチケットを作成してください。

有効になるまでは、GET /v1/models はどのモデルにも prompt_expand を表示しません。対応するモデルに prompt_expand: true を送ると、次のレスポンスが返ります。

{
  "error": {
    "message": "...",
    "type": "permission_error",
    "code": "feature_not_enabled",
    "param": "prompt_expand"
  }
}

ステータスは 403 です。料金は確保されず、プロバイダーにも何も送信されないため、拒否されたリクエストは無料です。判定には message ではなく code を使ってください。

次のステップ

関連記事