Postman または cURL による画像・動画生成 API のテスト - Model Studio

この Topic では、Postman と cURL を使用して Alibaba Cloud Model Studio の画像または動画生成 API を呼び出す方法について説明します。ここでは、テキストからの画像生成を例に、タスクの作成から結果の取得までの完全なフローを説明します。

Postman：直感的なインターフェイスを持つグラフィカルな HTTP テストツールです。初心者に推奨します。
cURL：コマンドラインインターフェイスに精通している開発者向けの強力なコマンドラインツールです。

説明

Postman および cURL は、迅速なテストと機能検証のみを目的としています。本番環境では、公式 SDK を使用するか、独自の HTTP 呼び出しを実装してください。

非同期 API 呼び出しの仕組み

画像および動画生成タスクは、数十秒から数分かかる場合があり、時間がかかることがあります。長時間の待機や HTTP 接続のタイムアウトを防ぐため、API は非同期呼び出しメカニズムを使用しています。このプロセスには 2 つのステップが含まれます：

タスクの作成：API を呼び出してタスクを作成します。サービスは同期的にタスク ID (task_id) を返します。
結果のクエリ：task_id を使用してタスクのステータスをポーリングします。タスクが完了すると、最終的な画像または動画の URL を取得できます。

HTTP 呼び出しの例 (テキストからの画像生成)

方法 1：Postman を使用したリクエストの送信 (推奨)

cURL コマンドから Postman を設定する方法

cURL の例を Postman リクエストに変換する際、パラメーターは次のように対応します：

cURL パラメーター	Postman インターフェイス	説明
`curl -X POST` または `curl -X GET`	リクエストメソッドのドロップダウンリスト	HTTP リクエストメソッドを選択します。
`https://<api-endpoint-url>`	URL 入力ボックス	API のリクエストアドレスです。
`-H 'Key: Value'`	[ヘッダー] タブ	リクエストヘッダーを設定します。キーと値のペアとして表示されます。
`-d '{...}'`	[ボディ] タブ	リクエストボディを設定します。

前提条件

API を呼び出す前に、ご利用のリージョン用の API キーを作成し、Postman をダウンロードしてください。

ステップ 1：タスクの作成

次の cURL コマンドに基づいて Postman を設定します。

次の base_url はシンガポールリージョン用です。リージョンごとに異なる base_url を使用します。

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

Postman で、[新規] または + をクリックして新しいリクエストを作成します。リクエストタイプとして [HTTP] を選択します。
リクエストメソッドのドロップダウンメニューから [POST] を選択し、ご利用のモデルのリージョンに対応する URL を入力します：
- シンガポール： https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
- 米国 (バージニア)： https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
- 北京： https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

[ヘッダー] タブをクリックし、次の 3 つのキーと値のペアを追加します。

キー	値	説明
X-DashScope-Async	enable	非同期呼び出しを有効にします。
Authorization	Bearer sk-xxx (sk-xxx をご利用の Model Studio API キーに置き換えます)	本人確認用の認証情報です。
Content-Type	application/json	リクエストボディが JSON 形式であることを宣言します。

リクエストボディ (Body) を設定します
- [ボディ] タブをクリックし、[raw] ラジオボタンを選択し、右側のフォーマットドロップダウンメニューから [JSON] を選択します。cURL の例で -d の後にある JSON コンテンツを入力ボックスに貼り付けます。
```
{
    "model": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}
```
- (任意) ページの右側にある Beautify をクリックして、JSON をフォーマットし、読みやすくします。
[送信] をクリックしてリクエストを送信し、task_id を取得します。ID は 24 時間有効です。有効期限が切れると、タスクをクエリできなくなります。結果は速やかに取得してください。

ステップ 2：task_id による結果のクエリ

task_id を取得したら、クエリ API を使用して最終結果を取得します。

シンガポール： https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}
米国 (バージニア)： https://dashscope-us.aliyuncs.com/api/v1/tasks/{task_id}
北京： https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Postman でクエリリクエストを設定します：
1. 新しい HTTP リクエストを作成します。
2. リクエストメソッドを [GET] に設定します。
3. ご利用のリージョンのクエリ URL を入力します。URL の {task_id} を、ステップ 1 で取得した実際の task_id に置き換えます。
4. [ヘッダー] タブで、Authorization キーを追加します。ステップ 1 と同じ API キーの値を使用します。
5. リクエストを送信するには、[送信] をクリックします。
返された結果を確認します。`task_status` が `SUCCEEDED` に変わるまでこのリクエストを繰り返し送信 (ポーリング) し、画像 URL を取得します。画像 URL は 24 時間有効です。速やかにダウンロードしてください。

方法 2：cURL を使用したリクエストの送信

コマンドラインに精通している開発者は、cURL を使用して API を迅速にテストできます。

前提条件

cURL コマンドを実行する前に：

Model Studio を有効化し、API キーを取得します。
ご利用のシステムに cURL がインストールされており、API キーを環境変数としてエクスポート済みであることを確認してください。これにより、$DASHSCOPE_API_KEY 変数を直接参照できます。
cURL がインストールされているかの確認
次のコマンドを実行して、cURL がインストールされているかを確認します。
```
curl --version
```
次のような出力が表示された場合、cURL はインストールされています：
```
curl 8.x.x (x86_64-apple-darwin23.0) libcurl/8.x.x (SecureTransport) LibreSSL/3.3.6 zlib/1.2.12 nghttp2/1.58.0
Release-Date: 2023-10-11
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtsp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS GSS-API HSTS HTTP2 HTTPS-proxy IPv6 Kerberos Largefile libz MultiSSL NTLM NTLM_WB SPNEGO SSL threadsafe UnixSockets
```
インストールされていない場合は、次のようなメッセージが表示されることがあります：
- Windows： 'curl' is not recognized as an internal or external command, operable program or batch file。
- Linux/macOS： command not found: curl。
cURL ダウンロードページにアクセスしてインストールしてください。

ステップ 1：タスクの作成

ターミナルで次のコマンドを実行します：

次の base_url はシンガポールリージョン用です。リージョンごとに異なる base_url を使用します。

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

リクエストが成功すると、task_id が返されます。ID は 24 時間有効です。有効期限が切れると、タスクをクエリできなくなります。結果は速やかに取得してください。

ステップ 2：task_id による結果のクエリ

次のコマンドの {task_id} をステップ 1 で取得したタスク ID に置き換えます。その後、コマンドをターミナルにコピーして実行します。
次の base_url はシンガポールリージョン用です。リージョンごとに異なる base_url を使用します。
```
curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
```
task_status が SUCCEEDED の場合、応答には画像 URL が含まれます。画像 URL は 24 時間有効です。URL の有効期限が切れる前に画像をダウンロードしてください。
タスクの処理には、数十秒から数分かかることがあります。このエンドポイントをポーリングする必要がある場合があります。task_status が RUNNING でなくなるまで、3～5 秒ごとにエンドポイントに問い合わせます。

次のステップ

最初の画像を生成したら、次のオプションを試してみてください：

API パラメーターの詳細：入力および出力パラメーターの詳細については、「テキストからの画像生成 API リファレンス」をご参照ください。
動画生成を試す：ファーストフレームからビデオへの API を呼び出して、動的な動画を作成します。
他のモデルを閲覧する：モデルリストにアクセスして、Model Studio がサポートするすべての画像および動画モデルを表示します。