既存 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 で再問い合わせます。非同期(動画など)は各社どおり「作成 → 照会」です。
次
- 新規、または特定ベンダーのフィールドに寄せたくない場合は lashot API。
- メソッドとフィールドはコンソールの すべてのエンドポイント。