既存 SDK でつなぐ

火山の画像・動画モデル

外部の参照素材を利用する場合、対象プロジェクトへの保護された取り込み用に assets:write が必要です。参照なしの画像・動画生成には取り込み権限は不要です。

拉鏡の Key と base_url="https://api.lashot.tianyunai.com/compat/ark/api/v3" を使用します。モデル呼び出し、認証、プロジェクト権限、タスク保存、課金を拉鏡が一括して提供します。独自の ep-... ではなくプラットフォームのモデル名を指定します。

火山方舟 SDK はモデルの実行チャネルに依存せず、拉鏡の統一プロトコルへ接続します。接続・公開されたモデルは対応済みのメソッドで利用でき、チャネル変更時も SDK と呼び出し先を変更する必要はありません。バージョン、パラメータ、参照素材の能力は最新のモデル一覧に従います。同名のモデルが複数ある場合は、一覧が返す完全なプラットフォーム識別子を指定してください。テキスト、音声、その他の SDK リソースの対応範囲は後述します。

公式 Python パッケージ volcengine-ark-runtime をインストールし、from volcenginesdkarkruntime import Ark を利用します。max_retries=0 を指定し、論理リクエストごとに一意の Idempotency-Key を保存してください。不明な結果は元のタスクを照会し、有料生成を再送しません。画像は images.generate(model="seedream-4.5", prompt="a lighthouse", size="2K", response_format="url", extra_headers={"Idempotency-Key": saved_key})。動画は content_generation.tasks.create(model="seedance-1.0-pro-fast", content=[{"type":"text","text":"a lighthouse"}], duration=2, resolution="480p", ratio="16:9", extra_headers={"Idempotency-Key": saved_video_key}) で作成し、content_generation.tasks.get(task_id=result.id) で照会します。

Seedream 4.5 / 5.0 Lite / 5.0 Pro / 5.5 と、提供中の Seedance 12 種に対応します。サイズ・時間・音声・参照枠は現在のモデル契約に従います。画像の image は HTTPS URL または配列、動画の content は画像・動画・音声 URL と開始/終了フレーム等の役割を保持します。URL は保護された素材取り込みを経由します。非公開入力は取り込み後に統一 API の素材参照を利用し、外部 URL に Key を送信しないでください。extra_body={"project_id":"project-uuid"} でプロジェクトを指定できます。

画像の同期待機は約 60 秒です。202 または結果が空の場合は GET /v1/jobs/{lashot_job_id} で状態を確認します。非公開出力は下記の同一オリジン認証で取得します。ストリーミング、Base64 出力、連続画像生成、5.5 のレイヤー分離は明示的に拒否します。テキスト・音声・素材審査は POST /v1/generations を利用し、Ark Chat 等すべての SDK リソースへの対応を意味しません。顧客の割当プランとタスク作成時に固定された価格で課金します。

すでに Ark、DashScope、Kling、MiniMax、千帆を利用している場合、対応済みのリクエスト項目を再利用し、アドレスとキーを lashot に切り替えます。非公開メディアの取得には、以下の認証対応も必要です。

$LASHOT_BASE には実際に配置した API のアドレスを設定します。ローカル開発は http://localhost:8080、本番のアドレスは管理者に確認してください。この手順は公開本番サービスの稼働を保証するものではありません。

コンソールの キー で発行し、SDK の api_key に入れます。生成・照会には generations:write/read、メディア取得にはさらに assets:read と現在のプロジェクトへのアクセス権が必要です。

変える場所

いま使っているもの 新しい base URL
火山方舟 Ark $LASHOT_BASE/compat/ark/api/v3
通義万相 DashScope $LASHOT_BASE/compat/dashscope/api/v1
Kling $LASHOT_BASE/compat/kling/v1
MiniMax $LASHOT_BASE/compat/minimax
百度千帆 $LASHOT_BASE/compat/qianfan/v2

認証の書き方は各社 SDK のまま。サーバーは Authorization: Bearer と x-api-key の両方を受けます。

開放済みのモデルとフィールドだけを受け付け、余分なパラメータは 400 です。新規の非公開プロジェクトの結果は /v1/asset-versions/{id}/content 形式のルート相対パスです。$LASHOT_BASE の API origin を基準に解決し、この同一オリジンの内容取得パスにだけ現在の Bearer キーを送信します。取得ごとにアクセス権とメディア審査を確認します。外部ストレージへの認証情報の送信や、認証情報付きのリダイレクト追跡は行わないでください。認証なしで取得する公式 SDK のダウンローダーには、この対応を追加する必要があります。

最短例(Ark の画像)

Ark 入口のサンドボックス名は sandbox-image(lashot では sandbox/image)。

curl -sS -X POST "$LASHOT_BASE/compat/ark/api/v3/images/generations" \
  -H "Authorization: Bearer $LASHOT_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "sandbox-image",
    "prompt": "a lighthouse at dusk, long exposure",
    "size": "1024x1024",
    "response_format": "url"
  }'

Python の Ark SDK のリクエスト例です。タスクや結果を表示するだけで、ファイルの取得はまだ行いません。

from volcenginesdkarkruntime import Ark
import os

client = Ark(
    base_url=os.environ["LASHOT_BASE"] + "/compat/ark/api/v3",
    api_key=os.environ["LASHOT_KEY"],
)
print(client.images.generate(
    model="sandbox-image",
    prompt="a lighthouse at dusk, long exposure",
    size="1024x1024",
    response_format="url",
))

同期は最大およそ 60 秒待ち、タイムアウト時は 202 とジョブ id で再問い合わせます。非同期(動画など)は各社どおり「作成 → 照会」です。

次