画像 API ドキュメントのよくある質問 - Alibaba Cloud Model Studio

Alibaba Cloud Model Studio の画像 API に関するよくある質問です。デバッグ、課金、レート制限、API エラーについて説明します。

デバッグ

画像 API 呼び出しをローカルでデバッグするにはどうすればよいですか？

画像 API は標準の HTTP を使用します。この例では、curl を使用して Wanx text-to-image API を呼び出します。

モデルサービスをアクティベートして API キーを取得し、それを環境変数として設定します。
API ドキュメントで curl コマンドを見つけます。例：

例：text-to-image の curl コマンド

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": "wanx2.1-t2i-turbo",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

macOS または Linux では、ターミナルでコマンドを直接実行します。
Windows では、Postman や Apifox などの API プラットフォームを使用して HTTP リクエストを送信します。

注： API プラットフォームを使用する場合、Authorization ヘッダーの $DASHSCOPE_API_KEY を、Bearer sk-xxxxxx のように実際の API キーに置き換えてください。

課金とレート制限

画像モデルの課金はどのように行われますか？

各画像モデルには無料クォータがあり、画像ごとの価格が設定されている場合があります：

モデル	無料クォータ	単価	タスク送信の QPS 制限	同時実行タスク数
画像モデル 1	500 画像	期間限定で無料	2	1
画像モデル 2	500 画像	$0.02 / 画像	2	1

無料クォータとレート制限は、Alibaba Cloud アカウントとすべての RAM ユーザー間で共有されます。

「期間限定で無料」とはどういう意味ですか？

モデルはパブリックプレビュー段階です。無料クォータを使い切ると、モデルは利用できなくなります。

課金対象となる画像は何ですか？

正常に生成された画像のみが課金対象です。入力画像や失敗したリクエストは、クォータを消費したり、料金が発生したりすることはありません。

無料クォータを取得するにはどうすればよいですか？

無料クォータは、Model Studio をアクティベートすると自動的に付与されます。有効期間は 90 日間で、アカウントとすべての RAM ユーザー間で共有されます。

詳細については、「新規ユーザー向けの無料クォータ」をご参照ください。

有料課金はいつから始まりますか？

特定の単価 (例：$0.02 / 画像) が設定されているモデルは商用化されています。無料クォータを使い切るか、有効期限が切れると課金が開始されます。

料金は Alibaba Cloud アカウントに請求されます。すべての使用量は親アカウントに集約されます。

請求書の表示： Alibaba Cloud 管理コンソールの [Billing Overview] ページに移動します。
資金の追加： 課金管理ページに移動します。
使用状況の監視： Model Studio プラットフォームの監視ページ (シンガポール | 北京) を確認してください。

課金の詳細については、「課金項目」をご参照ください。

API エラー

画像 API の一般的なエラーと解決策：

エラーコード	メッセージ	典型的な原因
`BadRequest.InputDownloadFailed`	Reference image download failed	画像 URL が正しくない、到達できない、またはアクセスが制限されている
`InvalidParameter`	url error, please check url	`model` パラメーターが、画像生成モデル名ではなく、テキスト生成モデル名に設定されている
`InvalidParameter`	Required body invalid	リクエストボディに、クライアントが解析できない中国語文字が含まれている
(Timeout)	Download the media resource timed out	中国本土以外のリージョンとサービスエンドポイント間のネットワークが不安定である

`BadRequest.InputDownloadFailed`：「Reference image download failed」

{
    "request_id": "657f0d1b-76d0-9e3e-b6d6-xxxxxx",
    "output": {
        "task_id": "5e6fa974-9a25-4271-8659-xxxxxx",
        "task_status": "FAILED",
        "code": "BadRequest.InputDownloadFailed",
        "message": "Reference image download failed, please check image url."
    }
}

原因： 画像 URL が正しくない、到達できない、またはアクセスが制限されています。サービスは処理中にその URL から画像をダウンロードします。

解決策： URL が完全で、パブリックにアクセス可能であることを確認してください。画像に認証が必要な場合は、OSS などのパブリックストレージサービスにアップロードし、新しい URL を使用してください。

`InvalidParameter`：「url error」

{
    "code": "InvalidParameter",
    "message": "url error, please check url！"
}

原因： model パラメーターが、呼び出されているエンドポイントと一致していません。画像合成エンドポイント (/api/v1/services/aigc/text2image/image-synthesis) は、画像生成モデル名のみを受け付けます。リクエスト URL が正しくても、qwen-turbo のようなテキスト生成モデル名が指定されると、url error で拒否されます。OpenAI 互換モードでは、代わりにテキスト生成モデル名が空のレスポンスを返します。

解決策： model を wanx2.1-t2i-turbo のような画像生成モデル名に設定し、エンドポイントを非同期で呼び出してください。

例： curl コマンドによる画像生成

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": "wanx2.1-t2i-turbo",
    "input": {
        "prompt": "a cute cat"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

画像生成は非同期です。タスク作成の呼び出しは task_id を返します。生成された画像の URL を取得するには、task_status が SUCCEEDED になるまで GET /api/v1/tasks/{task_id} をポーリングしてください。

`InvalidParameter`：「Required body invalid」

{
    "request_id": "d306ae65-3f6d-9d6c-acfb-xxxxxx",
    "code": "InvalidParameter",
    "message": "Required body invalid, please check the request body format."
}

原因： curl のリクエストボディに、クライアントが解析できない中国語文字が含まれています。

解決策： macOS または Linux では、ターミナルで curl を直接実行してください (ネイティブで UTF-8 を処理します)。Windows では、Postman や Apifox のような API プラットフォームを使用してください。

例： curl コマンドによる画像背景生成

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/background-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wanx-background-generation-v2",
    "input": {
        "base_image_url": "https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/main_images/new_main_img/a.png",
        "ref_image_url": "http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_images/c5e50d27be534709817b2ab080b0162f_0.jpg",
        "ref_prompt": "mountains and sunset clouds",
        "reference_edge": {
            "foreground_edge": [
                "https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/huaban_soft_edge/6cdd13941cef1b11d885aea1717b983ae566b8efc9094-vcsvxa_fw658webp.png",
                "http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_edge/2c36cc4b7da027279e87311dac48fc2d5d784b1e72c0e-x4f1wC_fw658webp.png"
            ],
            "background_edge": [
                "http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_edge/0718a9741e07c52ca5506e75c4f2b99e22fff68a4c7d3-P9WGLr_fw658webp.png"
            ],
            "foreground_edge_prompt": [
                "pink peach blossoms",
                "cute puppy"
            ],
            "background_edge_prompt": [
                "leaves"
            ]
        }
    },
    "parameters": {
        "n": 4,
        "ref_prompt_weight": 0.5,
        "model_version": "v3"
    }
}'

中国本土以外からのリソースダウンロードのタイムアウト

Download the media resource timed out during the data inspection process

原因： 中国本土以外のリージョンと DashScope サービスエンドポイント間のネットワークが不安定なため、ダウンロードがタイムアウトします。

解決策： 画像リソースを中国本土内に保存し、アクセラレーションを設定してください。タイムアウト期間は設定できません。