# bailian-image

Part of **BAILIAN**

# Alibaba Cloud Model Studio Image, Video, and 3D Generation Troubleshooting Guide

## Problem Index

| Problem | Symptom | Severity | Solution Summary |
|---------|---------|----------|------------------|
| Reference Image Download Failed | `BadRequest.InputDownloadFailed` | High | Verify image URL is publicly accessible or upload to OSS |
| Request Body Parsing Error | `InvalidParameter` | Medium | Use UTF-8 compatible clients like terminal curl or Postman |
| Media Resource Download Timeout | `Timeout` | High | Store image resources within the Chinese mainland and configure acceleration |
| Rate Limit Exceeded | HTTP 429 or task rejection | Medium | Implement retry logic and respect 2 QPS and 1 concurrent task limits |

## Problem Details

### Problem 1: Reference Image Download Failed

**Symptoms**
- Error message: `BadRequest.InputDownloadFailed`
- Behavior: The API request fails when providing a reference image or base image for background generation.
- Context: Occurs when using endpoints like background generation with `base_image_url` or `ref_image_url`.

**Root Cause**
- The provided image URL is incorrect, unreachable, or access-restricted. The DashScope service cannot download the media resource from the provided link.

**Solution**
1. Verify that the URL is complete and publicly accessible without authentication.
2. If the image requires authentication or is hosted on a private network, upload the image to a public storage service like Alibaba Cloud OSS.
3. Update your API request with the new, publicly accessible OSS URL.

**Verification**
- Resubmit the API request. The response should return a `200 OK` status with a valid `task_id` in the `output` field, and the task status should eventually become `SUCCESS`.

### Problem 2: Request Body Parsing Error

**Symptoms**
- Error message: `InvalidParameter`
- Behavior: The API rejects the request, stating the required body is invalid.
- Context: Typically occurs when sending prompts or parameters containing non-ASCII characters via certain HTTP clients.

**Root Cause**
- The HTTP client being used cannot correctly parse or encode the characters in the request body, resulting in malformed JSON or invalid UTF-8 encoding reaching the server.

**Solution**
1. If you are on macOS or Linux, run the `curl` command directly in the terminal, as it handles UTF-8 encoding natively.
   ```bash
   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"
           },
           "parameters": {
               "size": "1024*1024",
               "n": 1
           }
       }'
   ```
2. If you are on Windows, avoid using the default command prompt or PowerShell for complex JSON payloads. Instead, use an API platform like Postman or Apifox which handles character encoding correctly.

**Verification**
- The API should successfully parse the request body and return a valid JSON response containing a `request_id` and `task_id`.

### Problem 3: Media Resource Download Timeout

**Symptoms**
- Error message: `Timeout`
- Behavior: The task fails during the processing phase because the service cannot download the input media resource within the allowed time.
- Context: Frequently occurs when the input image is hosted in regions outside the Chinese mainland.

**Root Cause**
- Network instability or high latency between the region where the image is hosted (outside the Chinese mainland) and the DashScope service endpoint.

**Solution**
1. Store your image resources within the Chinese mainland (e.g., using an OSS bucket located in a Chinese mainland region).
2. Configure network acceleration for your storage bucket if necessary to ensure fast download speeds.
3. Note: The timeout period is strictly managed by the service and is not configurable by the user.

**Verification**
- Submit a new task using the mainland-hosted image URL. The task should complete successfully without triggering a timeout error.

### Problem 4: Rate Limit and Concurrency Restrictions

**Symptoms**
- Error message: HTTP `429 Too Many Requests` or tasks remaining in `PENDING` state for extended periods.
- Behavior: API requests are rejected or heavily delayed when submitting multiple image generation tasks simultaneously.

**Root Cause**
- The image generation API enforces strict rate limits: 2 Queries Per Second (QPS) for task submission and a maximum of 1 concurrent task processing at a time.

**Solution**
1. Implement a queuing mechanism in your application to ensure only one task is processing at a time.
2. Add exponential backoff and retry logic for task submission to handle the 2 QPS limit.
3. Check the status of the current task before submitting a new one.
   ```json
   {
       "output": {
           "task_id": "5e6fa974-9a25-4271-8659-xxxxxx",
           "task_status": "SUCCESS"
       }
   }
   ```

**Verification**
- Monitor your application logs to confirm that tasks are being submitted sequentially and no HTTP 429 errors are returned.

## FAQ

**Q: How am I billed for image generation API calls?**
A: Billing is based on a per-image model. Only successfully generated images are billed. Input images and failed requests do not incur charges. There is a free tier of 500 images (valid for 90 days, shared across the account and RAM users). Charges begin only after the free quota is exhausted or expires.

**Q: What are the exact rate limits for the image generation API?**
A: The rate limit is 2 QPS for task submission, and you can only have 1 concurrent task processing at any given time.

**Q: How do I authenticate my API requests?**
A: You must use a Bearer token in the HTTP header. Set the `Authorization` header to `Bearer $DASHSCOPE_API_KEY`, where the API key is stored in your environment variables.

**Q: Can I configure the timeout period for downloading media resources?**
A: No, the timeout period for downloading media resources is managed by the platform and is not configurable. To avoid timeouts, ensure your resources are hosted in the Chinese mainland with proper acceleration.

**Q: Where are the generated images stored?**
A: Generated images are temporarily stored in the DashScope result OSS bucket. The API response provides a URL in the `output.result[].url` field. You should download and save the image to your own persistent storage, as the temporary URL will eventually expire.

## Source Documents

- `FAQ_5476558.xdita`