imini-generate

imini オープンプラットフォーム API 統合

imini で画像や動画を生成するか、ユーザーのプロジェクト向けの統合コードを作成します。適切なモデルを選び、コストを見積もり、非同期タスクを処理します。

imini について

• 統一エンドポイント：https://openapi.imini.ai/imini/router
• 統一認証：1 つの Bearer API キーですべてのモデルを利用できます — Authorization: Bearer $IMINI_API_KEY
• 統一非同期パターン：すべての生成呼び出しで task_id が返されます。status が succeeded または failed になるまで、タスク照会エンドポイントをポーリングします。有効な値は queued / processing / succeeded / failed の 4 つです — pending / completed / running は確認しないでください。
• 統一エラー形式：{ error: { code, message, status, request_id } }
• カタログ：https://docs.imini.ai/llms.txt — 価格とモデルごとの OpenAPI 仕様 URL を含む、常に最新のモデル一覧です。

ステップ 0 — 適切な経路を選ぶ

経路は 2 つあります。ほかのことを始める前に選んでください。

ユーザーの発言…	経路	実行すること
「…の[画像 | 動画]を生成して／作って／描いて／作成して」	A	同梱スクリプトを実行します — コード生成は不要です
「このプロンプトで imini を試して」／「…がどのように見えるか見せて」	A	同様です
「自分のプロジェクト／アプリ／バックエンドに imini を追加して」	B	ユーザーの言語でコードテンプレートを生成します
「imini を呼び出す Python／Node／TS 関数を書いて」	B	同様です
「imini で X ができるかテストして」	A の後、コードも必要か確認します
ユーザーの意図が不明確	「今すぐ 1 回だけ生成しますか。それともプロジェクト用の統合コードが必要ですか？」と尋ねます

2 つの経路ではモデルに関する知識（references/model_selection.md）を共有しますが、references/integration_examples.md を読む必要があるのは経路 B だけです。経路 A でこのファイルを読み飛ばすことが、トークン効率を高める主なポイントです。

---

経路 A — 1 回限りの生成（同梱スクリプト）

このスキルには、送信、ポーリング、429／5xx の再試行、ジッター、構造化エラーの保持、結果のダウンロードを処理する実行可能な Python スクリプトが含まれています。スクリプトを呼び出してください。毎回、その場しのぎの Python コードでこのロジックを書き直す必要はありません。

A1 — 事前確認

スクリプトを実行する前に、次のことを確認します。

1. Python の確認：python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3,8) else 1)' — 成功する必要があります。失敗した場合は、Python 3.8 以降をインストールするようユーザーに伝えてください（macOS：標準搭載、Ubuntu：sudo apt install python3、Windows：winget install Python.Python.3）。
2. API キーの確認：[ -n "$IMINI_API_KEY" ] && echo OK || echo MISSING。キーが設定されていない場合は、シェルに設定するようユーザーに案内します（export IMINI_API_KEY='sk-...'）。キーを会話に貼り付けるよう求めないでください。エージェントのトランスクリプトに記録されてしまいます。キーは https://imini.ai/api-keys で管理できます。

A2 — モデルを選ぶ（最新情報を取得し、ハードコードしない）

ユーザーがモデルを指定していない場合は、次を実行します。

python3 ${SKILL_DIR}/scripts/generate_image.py --list-models    # for images
python3 ${SKILL_DIR}/scripts/generate_video.py --list-models    # for videos

カタログを https://docs.imini.ai/llms.txt から取得し（24 時間のオフラインキャッシュを使用）、モデル ID、機能の概要、価格、OpenAPI 仕様 URL を出力します。モデル一覧をハードコードして管理しないでください — imini が新しいモデルを公開すると、すぐに利用できるようになります。

指定されたニーズに合うモデルを選ぶには、references/model_selection.md を参照してください。参照動画を使った Seedance など、複雑なケースの正確な価格については、https://docs.imini.ai/en/guide/pricing を案内してください。

A3 — スクリプトを実行する

画像（1 枚、1080p 程度、4K 解像度）：

python3 ${SKILL_DIR}/scripts/generate_image.py \
    --model google/nano-banana-pro \
    --prompt "a moody cinematic portrait at golden hour" \
    --resolution 4K --aspect-ratio 16:9 \
    --output ./out.png

スタイルとアセット参照を使った画像：

python3 ${SKILL_DIR}/scripts/generate_image.py \
    --model google/nano-banana-pro \
    --prompt "place the product in this style" \
    --style-reference ./mood.jpg \
    --reference-image ./product.png \
    --resolution 2K --aspect-ratio 1:1 \
    --output ./out.png

動画（音声付き、1080p、5 秒）：

python3 ${SKILL_DIR}/scripts/generate_video.py \
    --model kling/kling-v3 \
    --prompt "drone shot over snowy mountains at sunrise" \
    --duration 5 --resolution 1080P --aspect-ratio 16:9 \
    --audio \
    --output ./drone.mp4

最初と最後のフレームを補間する動画：

python3 ${SKILL_DIR}/scripts/generate_video.py \
    --model kling/kling-v3 \
    --prompt "smooth camera move from sunrise to sunset" \
    --start-image ./first.jpg --end-image ./last.jpg \
    --duration 10 --resolution 720P \
    --output ./interp.mp4

実行時間の長い動画 — 起動したら、完了を待たずに離れられます：

# Submit only, returns task_id immediately
TASK_ID=$(python3 ${SKILL_DIR}/scripts/generate_video.py \
    --model doubao/seedance-2.0 \
    --prompt "..." --duration 15 --resolution 720P \
    --reference-video ./ref.mp4 \
    --async)
echo "task_id: $TASK_ID"

# Later — resume polling and download
python3 ${SKILL_DIR}/scripts/poll_video_task.py --task-id "$TASK_ID" --output ./out.mp4

A4 — 一般的な CLI パターン

4 つのスクリプトは、次のフラグを共通で使用します。

• --print-request — 送信される JSON 本文を出力して終了します。API キーは不要です。クレジットを消費する前に確認するのに便利です。
• --no-download — ファイルのダウンロードをスキップし、代わりに結果の URL を標準出力に出力します。
• --quiet — 保存先の最終パスのみを出力します。
• --verbose — デバッグレベルのポーリング詳細を表示します。
• --api-key KEY — $IMINI_API_KEY を上書きします（非推奨です。シェルの履歴に記録されます）。
• --timeout SECONDS — デフォルトのハードタイムアウトを上書きします。デフォルト値は一律で、画像は 600s（10 min）、動画は 1800s（30 min）です。正式な数値については references/errors.md を参照してください。
• --list-models — llms.txt から最新のモデルを取得して出力します（24h キャッシュ）。
• --refresh-cache — llms.txt を強制的に再取得します。

明示的なフラグが用意されていないフィールドには、次の拡張オプションを使用してください。

• --extra '<json>' — リクエスト本文のルートレベルにマージします。
• --extra-params '<json>'（動画のみ）— extra_params にマージします（Kling のマルチショット、camera_control、negative_prompt など、happyhorse の audio_setting）。

A5 — 結果をユーザーに報告する

スクリプトが正常に終了すると、saved → <path> (<bytes>, <wxh>) と出力されます。保存先のパス、使用したモデル、長さや解像度のメタデータ、概算のクレジット費用（カタログに基づく）を提示し、ユーザーが使用額を把握できるようにしてください。

複数画像の結果（--num-images > 1）では、スクリプトが保存したファイルパスをすべて処理し、[0] があると決めつけないでください。

---

パス B — ユーザーのプロジェクト用の統合コード

ユーザーが imini を単発のファイルとして現在の作業ディレクトリに保存するのではなく、自分のコードベースに組み込むことを希望する場合は、コードテンプレートを生成します。

B1 — API キーを取得する

ユーザーが imini の API キーを持っていることを確認します。https://imini.ai/api-keys を案内してください。生成するコードにキーをハードコードしないでください。 すべてのテンプレートで、環境変数（デフォルト名：IMINI_API_KEY）から読み取る必要があります。

B2 — 意図を確認する

モデルを選ぶために必要な質問だけをしてください。

1. 画像ですか、動画ですか？
2. 入力モダリティ：テキストのみ／参照画像／最初と最後のフレーム／参照動画／マルチモーダル？
3. 品質レベル（画像：1K／2K／4K／512、動画：480P／720P／1080P）
4. 長さ（動画のみ）
5. 統合に使用するプログラミング言語（Python／Node／TypeScript／cURL）

B3 — モデルを選ぶ

パス A と同じ方法でライブカタログ（scripts/generate_image.py --list-models または scripts/fetch_imini_catalog.py）を使用し、機能選択の判断ツリーとして references/model_selection.md も参照してください。モデル ID、要件への適合性、クレジット費用を含む候補を 1～2 件提示します。コードを書く前に、明示的な確認を得てください。

B4 — OpenAPI 仕様を取得する

選択したモデルの Spec: URL（例：https://docs.imini.ai/en/openapi/images/nano-banana-pro.yaml）から YAML を取得します。エージェントが利用できる HTTP 取得ツールを使うか、curl にフォールバックしてください。YAML 形式はクリーンな OpenAPI 3.1.0 で、決定的に解析できます。.md 形式よりもこちらを優先してください。

B5 — コードを生成する

references/integration_examples.md のテンプレートを使用してください。生成するコード一式には、必ず次の内容を含めてください。

1. 送信関数 — 生成エンドポイントに POST し、task_id を返します。
2. ポーリングループ — 指数バックオフ、±20% のジッター、429 時の最低 5 秒、ハードタイムアウトを適用して、タスク照会エンドポイントに GET します。succeeded と failed のみを条件分岐に使用してください。completed や running は使用しないでください。
3. 結果の抽出 — 画像タスクでは images[] を、動画タスクでは videos[] を返します。各要素には url と width / height が含まれます（動画には duration も含まれます）。配列は必ず反復処理してください。[0] をハードコードしてはいけません。 モデルやパラメーターによっては、複数の出力が生成されます。
4. 構造化エラーの保持 — 失敗時に error.code、error.message、error.request_id を提示し、ユーザーが request_id を記録して imini のサポートに問い合わせられるようにします。

対応するテンプレート言語：

• Python（同期、標準ライブラリのみ — urllib）
• Python（非同期、aiohttp ≥ 3.9 が必要）
• Node.js（ネイティブの fetch を使用するには Node 18+ が必要）
• TypeScript（Node 18+ が必要）
• cURL（2 段階：送信＋ポーリング。JSON の解析には python3 -c を使用）

B6 — 本番環境でのヒント

• API キーは環境変数で管理し、ハードコードしないでください。
• ポーリングの開始間隔：画像は約 2 秒、動画は約 5 秒です。指数バックオフは 1.5 倍、最大 30 秒とし、さらに ±20% のジッターを加えます。
• HTTP 429 が発生した場合は、次の試行の前にバックオフの最低間隔を 5 秒以上に引き上げます。
• タイムアウトについては、シナリオごとの正式な一覧を references/errors.md で確認してください。
• 同時実行にはセマフォまたはワーカープールを使用してください。同期ポーリングを並行して実行し、処理をブロックしないでください。
• コスト管理：送信ごとに task_id とクレジットの推定コストを記録し、上流でユーザーごとのクォータを設定してください。

---

参考ファイル

• references/workflow.md — 非同期タスクの状態機械とポーリング戦略の詳細
• references/model_selection.md — 機能に基づく意思決定ツリー（モデルの選択）
• references/integration_examples.md — 言語ごとの Path B コードテンプレート
• references/errors.md — 正式なタイムアウト一覧、エラーコード、再試行ポリシー
• scripts/_imini_common.py — 共通の送信／ポーリング／アップロード／ダウンロード／エラー処理ロジック（すべての同梱スクリプトで使用）
• scripts/generate_image.py — Path A：画像生成 CLI
• scripts/generate_video.py — Path A：動画生成 CLI
• scripts/poll_image_task.py — 画像タスクの task_id を使って再開
• scripts/poll_video_task.py — 動画タスクの task_id を使って再開
• scripts/fetch_imini_catalog.py — 元のカタログ取得ツール（生成スクリプトの --list-models は同じロジックを使用）

外部リソース

• プラットフォーム：https://imini.ai
• ドキュメント：https://docs.imini.ai
• 料金：https://docs.imini.ai/en/guide/pricing
• 変更履歴：https://docs.imini.ai/en/changelog
• サポート：[email protected]