PostmanまたはcURLを使用してHTTPリクエストを行う方法 - Alibaba Cloud Model Studio

この記事では、 Postman と cURL を使用して Alibaba Cloud Model Studio (百練) の画像または動画生成 API を呼び出す方法について説明します。このガイドでは、 Text-to-Image の例を使用して、タスクの作成から結果の取得までの全プロセスを解説します。

Postman：HTTP リクエストをテストするための直感的なグラフィカルツールです。初心者の方に推奨します。
cURL：コマンドライン操作に慣れた開発者向けの強力なコマンドラインツールです。

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

非同期呼び出しのメカニズム

画像・動画生成タスクは、完了までに 10 秒以上、場合によっては数分かかることがあります。長時間の HTTP 接続やタイムアウトを避けるため、API は非同期呼び出しのメカニズムを採用しています。このプロセスは、次の 2 つのステップに分かれています：

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

HTTP呼び出しの例 (Text-to-Image)

方法1：Postmanの使用 (推奨)

cURLからのPostman設定

cURL コマンドを Postman リクエストに変換する際、パラメーターは次のようにマッピングされます：

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

前提条件

API を呼び出す前に、リージョンに応じた API キーを取得し、Postman をダウンロードしてください。

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

次の cURL コマンドを使用して Postman を設定します。

次のベース URL はシンガポールリージョン用です。ご利用のリージョンに応じたベース URL を使用する必要があります。

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.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://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis。ワークスペース ID の取得で説明されているように、WorkspaceId を実際のワークスペース ID に置き換えます。
- 米国 (バージニア)： https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
- 中国 (北京)： https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
各リージョンでサポートされているモデルについては、Model Studio コンソールをご参照ください。現在のリージョンとサービスのデプロイ範囲は、事前定義されたシステムバインディング関係に基づいており、カスタムの組み合わせはサポートされていません。

POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

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

キー	値	説明	Postman では、[ヘッダー] タブで、[X-DashScope-Async] を `enable` に、[Authorization] を `Bearer <your-api-key>` に、[Content-Type] を `application/json` に設定します。
X-DashScope-Async	enable	非同期呼び出しを有効にします。
Authorization	Bearer sk-xxx (sk-xxx をご自身の 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 が取得されます。この task_id は 24 時間有効です。この期間を過ぎると、結果は照会できなくなります。速やかに結果を取得してください。

{
    "request_id": "896b2ccd-a0cd-40a8-a557-bb73cee5cf95",
    "output": {
        "task_id": "42442de9-917d-4c41-80a7-37fb7ad25ed2",
        "task_status": "PENDING"
    }
}

ステップ2：タスク IDによる結果の照会

タスク ID を取得したら、照会エンドポイントを呼び出して最終結果を取得します。

シンガポール: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis、WorkspaceId を実際のワークスペース ID に置き換えます。
米国 (バージニア)： https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
中国 (北京)： https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.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. [ヘッダー] タブで、ステップ 1 と同じ API キーを使用して Authorization ヘッダーを追加します。
5. [Send] をクリックします。

GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/42442de9-917d-4c41-80a7-37fb7ad25ed2

Headers:
Cookie: acw_tc=896b2ccd-a0cd-40a8-a557-bb73cee5cf957...
Postman-Token: <リクエスト送信時に計算されます>
Host: <リクエスト送信時に計算されます>
User-Agent: PostmanRuntime/7.49.1
Accept: */*
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Authorization: Bearer sk-xxx

レスポンスを確認します。task_status が SUCCEEDED になるまでこのエンドポイントをポーリングし、画像 URL を取得します。画像 URL は 24 時間有効です。24 時間以内に画像をダウンロードしてください。

"results": [
            {
                "orig_prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display",
                "actual_prompt": "A cozy and elegant flower shop, with an exterior decorated with exquisitely carved windows. The window frames are light-colored wood, set with transparent glass that reveals the soft light inside. The front door is a beautiful solid wood door that retains its natural grain, complemented by a brass handle and a vintage nameplate, giving it a quaint and textured feel. On both sides of the front steps, and on the windowsills and entrance area, various flowers—including roses, lilies, hydrangeas, and tulips—are arranged in a staggered, vibrant display. Some bouquets are wrapped in kraft paper and tied with twine, exuding a fresh, natural scent. The background features a quiet European town streetscape, with stone-paved roads and greenery adding to the charm. The overall image is in a realistic photographic style, with soft lighting and a warm color palette that highlights the shop's exquisite and romantic atmosphere.",
                "url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1d/3a/20251203/7a2bee47/42442de9-917d-4c41-80a7-37fb7ad25ed2.png?xxx"
            }
        ]

方法2：cURLの使用

コマンドライン操作に慣れた開発者は、cURL を使用して APIを素早くテストできます。

前提条件

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

モデルサービスをアクティブ化し、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' は、内部コマンドまたは外部コマンド、操作可能なプログラムまたはバッチファイルとして認識されていません。
- Linux/macOS： command not found: curl。
cURLのダウンロードページからインストールしてください。

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

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

次のベース URL はシンガポールリージョン用です。ご利用のリージョンに応じたベース URL を使用する必要があります。

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.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 時間有効で、有効期限が切れるとクエリには使用できなくなります。速やかに結果を取得してください。

curl -X POST https://dashscope.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
    }
}'
{"request_id":"ca3b5224-bc60-4e47-80f4-2790040e9e55","output":{"task_id":"2de3f7e1-52ce-4cf4-a466-f2d318061c43","task_status":"PENDING"}}

ステップ2：タスク IDによる結果の照会

次のコマンドの {task_id} をステップ 1 で取得したタスク ID に置き換え、コマンドをターミナルにコピーして実行します。

次のベース URL はシンガポールリージョン用です。ご利用のリージョンに応じたベース URL を使用する必要があります。

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

タスクが完了すると (task_status が SUCCEEDED)、レスポンスに画像 URL が含まれます。画像 URL は 24 時間有効です。速やかにダウンロードしてください。

モデルの処理には長い時間 (数十秒から数分) がかかるため、この API のポーリングが必要になる場合があります。task_status が RUNNING でなくなるまで、3～5 秒ごとに API をクエリすることをお勧めします。

curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/2de3f7e1-52ce-4cf4-a466-f2d3f8061c43 \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
{"request_id":"24143559-9964-4898-8f9c-d968bba182b9","output":{"task_id":"2de3f7e1-52ce-4cf4-a466-f2d3f8061c43","task_status":"SUCCEEDED","submit_time":"2025-12-03 10:19:18.293","scheduled_time":"2025-12-03 10:19:18.320","end_time":"2025-12-03 10:19:31.890","results":[{"orig_prompt":"A flower shop with exquisite windows, a beautiful wooden door, and flowers on display","actual_prompt":"A cozy, elegant flower shop. The exterior wall features exquisitely carved windows with dark brown wooden frames, and the glass is clean and bright, revealing the soft light inside. The front door is a beautiful solid wood door that retains its natural grain, complemented by a brass handle and a vintage nameplate that exudes a strong artisanal feel. On both sides of the front steps, and on the windowsills and entrance area, various flowers—including blooming roses, elegant hydrangeas, fresh daisies, and green eucalyptus leaves—are arranged in a staggered yet harmonious display. The background is a quiet European town streetscape, with a stone-paved road and a vine-covered neighboring wall enhancing the romantic atmosphere. The overall image is in a realistic photographic style, with soft, natural lighting that highlights the wood texture and floral details.","url":"https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1d/59/20251203/7a2bee47/2de3f7e1-52ce-4cf4-a466-f2d3f8061c43.png?Expires=1764814771&OSSAccessKeyId=YOUR_ACCESS_KEY_ID"}],"task_metrics":{"TOTAL":1,"FAILED":0,"SUCCEEDED":1}},"usage":{"image_count":1}}

curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/8b108773-4e7d-4cd7-8c62-aad7a08d7769 \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
{"request_id":"0ee9ab8a-0ea4-9f0b-9cb0-41eaf24fd5e8","output":{"task_id":"8b108773-4e7d-4cd7-8c62-aad7a08d7769","task_status":"SUCCEEDED","submit_time":"2025-12-03 10:50:24.253","scheduled_time":"2025-12-03 10:50:24.282","end_time":"2025-12-03 10:50:42.708","results":[{"orig_prompt":"A flower shop with exquisite windows, a beautiful wooden door, and flowers on display","actual_prompt":"A warm and elegant flower shop, with an exterior wall decorated with an exquisitely carved window. The window frame is dark brown solid wood, with clean and bright glass revealing the soft light inside. The front door is a beautiful wooden door crafted with a vintage distressed technique, its surface retaining the wood grain texture, complemented by a brass door handle and a small nameplate decoration, exuding a strong handmade feel. In front of the door, on the windowsill, and on both sides of the entrance, various flowers are arranged in a staggered fashion—pink and white roses, pale purple hydrangeas, bright yellow sunflowers, and green eucalyptus leaves—with soft and layered colors. The background is a quiet European-style street, with cobblestones and vine-covered neighboring walls adding a romantic atmosphere. The overall image is in a realistic photography style, with warm and natural lighting, highlighting the tranquility and beauty of the flower shop.","url":"https://dashscope-result-sgp.oss-ap-southeast-1.aliyuncs.com/1d/63/20251203/c3a8f0e2/24817593-8b108773-4e7d-4cd7-8c62-aad7a08d7769.png?Expires=1748416642&OSSAccessKeyId=YOUR_ACCESS_KEY_ID"}],"task_metrics":{"TOTAL":1,"FAILED":0,"SUCCEEDED":1}},"usage":{"image_count":1}}%

次のステップ

最初の画像の生成に成功したら、以下をお試しいただけます：

APIパラメーターの詳細：追加のパラメーターについては、Text-to-Image API のドキュメントをご参照ください。
動画生成の試用：First-Frame-to-Video API を試して動画を作成してみてください。
他のモデルの探索：Model Studio コンソールに移動して、Alibaba Cloud Model Studio (百練) がサポートするすべての画像・動画モデルを確認できます。