イメージ API ドキュメントのよくある質問 - Alibaba Cloud Model Studio

このトピックでは、デバッグ、課金、レート制限、一般的な API エラーなど、イメージ API に関するよくある質問に回答します。

このトピックで説明するイメージモデルには、Wan text-to-image V2、人物インスタンスセグメンテーション、およびイメージ消去補完が含まれます。

API をローカルでデバッグする

イメージ API は HTTP 呼び出しをサポートしています。次のセクションでは、Wan text-to-image API を例として、HTTP API 呼び出しをローカルでデバッグする方法を示します。

モデルサービスをアクティブ化して 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": "精巧な窓、美しい木製のドア、そして花が飾られた花屋"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

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

注: API プラットフォームを使用してリクエストを送信する場合、curl コマンド Bearer $DASHSCOPE_API_KEY の $DASHSCOPE_API_KEY を、Bearer sk-xxxxxx のように実際の API キーに置き換える必要があります。

課金とレート制限

課金の例

注: 表内のイメージモデル 1 とイメージモデル 2 は例であり、実際のモデル名ではありません。

モデル	無料クォータ (表示)	単価	レート制限 (Alibaba Cloud アカウントと RAM ユーザーで共有)
モデル	無料クォータ (表示)	単価	タスク送信の QPS 制限	同時タスク数
イメージモデル 1	500 イメージ	期間限定で無料	2	1
イメージモデル 2	500 イメージ	$0.02/イメージ	2	1

無料クォータ

説明: 無料クォータは、モデルによって正常に生成されたイメージの数に基づいています。入力イメージや失敗したモデル処理では、クォータは消費されません。
取得方法: 無料クォータは、Alibaba Cloud Model Studio サービスをアクティブ化した後に自動的に付与され、90 日間有効です。
使用方法: Alibaba Cloud アカウントとその RAM ユーザーは無料クォータを共有します。
詳細については、「新規ユーザー向けの無料クォータ」をご参照ください。

期間限定で無料

課金方法が「期間限定で無料」の場合、モデルはパブリックプレビュー中です。無料クォータを使い切った後は、モデルを使用できません。

課金の説明

$0.02/イメージなどの特定の単価が提供されている場合、モデルは商用化されています。無料クォータを使い切った後、または有効期限が切れた後にモデルを使用すると課金されます。
課金対象: 正常に生成された出力イメージに対してのみ課金されます。その他の場合は料金は発生しません。
課金方法: 料金は Alibaba Cloud アカウントに請求されます。RAM ユーザーは個別に測定または請求することはできません。すべての使用量は、RAM ユーザーを所有する Alibaba Cloud アカウントに請求されます。課金情報を表示するには、Alibaba Cloud 管理コンソールの [課金の概要] ページに移動します。
チャージ方法: Alibaba Cloud 管理コンソールの [支払いと費用] ページでアカウントに資金を追加できます。
モデル呼び出し統計: モデルの呼び出し量と回数を表示するには、Alibaba Cloud Model Studio プラットフォームのモデル監視 (シンガポールまたは北京) ページに移動します。
課金の詳細については、「課金対象」をご参照ください。

レート制限

説明: Alibaba Cloud アカウントとその RAM ユーザーはレート制限を共有します。

API エラー

イメージのダウンロードに失敗しました

シナリオ: ドキュメントのサンプル URL ではなく、独自のイメージ URL を使用して API をリクエストすると、「Reference image download failed, please check image url.」というエラーメッセージが返されます。

{
    "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 が完全であり、パブリックネットワークからのアクセスが許可されていることを確認してください。イメージは、パブリックにアクセス可能な自己管理ストレージサービス、または OSS などのクラウドストレージサービスにアップロードできます。イメージ URL がパブリックネットワークからのアクセスを許可していることを確認してください。

タスク作成 API の curl コマンドが失敗する

シナリオ: ドキュメントからタスク作成 API の curl コマンドをコピーして実行すると、エラーが発生します。例として、イメージ背景生成モデルの次の curl コマンドを使用します。

例: イメージ背景生成のタスク作成 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": "山と夕焼け雲",
        "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": [
                "ピンクの桃の花",
                "かわいい子犬"
            ],
            "background_edge_prompt": [
                "葉"
            ]
        }
    },
    "parameters": {
        "n": 4,
        "ref_prompt_weight": 0.5,
        "model_version": "v3"
    }
}'

「Required body invalid, please check the request body format.」というエラーメッセージが返されます。

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

考えられる原因: タスク作成 API のリクエスト本文に中国語の文字が含まれています。curl コマンドを実行するクライアントが中国語の文字の解析をサポートしていない場合、リクエスト本文が正しく解析されず、エラーが発生する可能性があります。

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

中国国外から API を呼び出す際のリソースダウンロードタイムアウト

シナリオ: 中国国外から API を呼び出し、イメージリソースが中国本土以外のリージョンに保存されている場合、リソースダウンロードのタイムアウトエラーが発生する可能性があります。エラーメッセージは次のとおりです。

Download the media resource timed out during the data inspection process

主な原因: 中国本土以外のリージョンとサービスエンドポイント間のネットワークが不安定なため、サービスがイメージをダウンロードしようとするとタイムアウトが発生する可能性があります。

解決策: イメージリソースを中国本土内のリージョンに保存し、アクセラレーションを設定します。Alibaba Cloud アカウントのイメージダウンロードタイムアウト期間は設定できないことに注意してください。

その他の質問

イメージ OSS リンクにアクセスするためのドメイン名ホワイトリストの設定

イメージモデルによって生成されたイメージは Alibaba Cloud OSS に保存されます。各イメージには、https://dashscope-result-xx.oss-cn-xxxx.aliyuncs.com/xxx.png のような OSS リンクが割り当てられます。イメージ OSS リンクはパブリックアクセスを許可します。このリンクを使用して、イメージを表示またはダウンロードできます。

ビジネスのセキュリティ要件が高く、内部ネットワークが Alibaba Cloud OSS リンクにアクセスできない場合は、外部ネットワークアクセス用にホワイトリストを設定する必要があります。イメージリンクにアクセスできるように、次のドメイン名をホワイトリストに追加します。

# イメージ OSS ドメイン名のリスト
dashscope-result-bj.oss-cn-beijing.aliyuncs.com
dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com