Wan 2.7 Image Pro API
/v1/tasks All models are called through the Unified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).
Model summary
| Model name | wan2.7-image/text-to-image |
|---|---|
| Type | Image generation (text-to-image) |
| Endpoint | POST /v1/tasks |
| Pricing | See HiAPI Pricing |
Alibaba Tongyi Wanxiang Wan 2.7 Pro text-to-image: up to 4K (~4096² pixels) output, strong prompt adherence, prompts in both Chinese and English, with in-image long-text rendering as an officially highlighted capability — built for posters, e-commerce shots and text-heavy design assets.
Production guidance
- For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
- GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
- Use callback.when=final. Both success and fail are terminal states, so your service should deduplicate by taskId.
Best suited for
Natively optimized for Chinese prompts, with stable photorealism on portraits, products and food, and accurate rendering of Chinese storefronts and signage — a strong fit for Chinese-market marketing assets.
promptThe 4K tier reaches roughly 4096² total pixels and costs the same as 1K/2K, so pick 4K for print materials or large displays at no extra cost.
resolutionLong-text rendering is an officially highlighted direction: write poster headlines, labels and signage text straight into the prompt, ideally quoted verbatim.
promptThe 8:1 / 1:8 ultra-wide tiers are rare among text-to-image models — suited for site-wide top banners, campaign strips and tall vertical layouts.
aspect_ratioRequest parameters
model string required Fixed value wan2.7-image/text-to-image.
input object required Business parameters. Put Wan 2.7 Image Pro-specific configuration here.
prompt string required Text prompt for image generation, in Chinese or English; 1-5000 characters, longer input is truncated automatically.
aspect_ratio enum optional Output aspect ratio. The ultra-wide 8:1 / 1:8 banner tiers are a distinctive option of this model.
resolution enum optional Resolution tier: roughly 1024² total pixels for 1K, 2048² for 2K (default) and 4096² for 4K. All three tiers cost the same.
thinking_mode boolean optional When enabled, the model uses enhanced reasoning for higher image quality at the cost of longer generation time. Off by default on HiAPI.
seed integer optional Random seed, 0-2147483647. The same seed produces similar results, but identical output is not guaranteed.
callback object optional Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.
url string required Required when callback is set; HTTPS URL that receives terminal task notifications.
when enum optional Callback trigger timing. Use final.
Example requests
Chinese prompts are natively supported — write the exact text you want in the image directly into the prompt.
{
"model": "wan2.7-image/text-to-image",
"input": {
"prompt": "现代咖啡馆店面，黄金时段暖光，木质吊牌写着 WAN CAFE，橱窗暖黄灯光，行人路过，照片级写实，高细节",
"aspect_ratio": "3:4",
"resolution": "2K"
}
}4K costs the same as 1K/2K, so go straight to 4K for product and food imagery where detail matters.
{
"model": "wan2.7-image/text-to-image",
"input": {
"prompt": "Overhead flat-lay food photography of a vibrant Korean bibimbap in a black stone bowl, colorful fresh vegetables, sesame seeds, soft natural light, ultra detailed",
"aspect_ratio": "1:1",
"resolution": "4K"
}
}A distinctive ultra-wide tier: generate site-wide top banners and campaign strips in one shot, no stitching needed.
{
"model": "wan2.7-image/text-to-image",
"input": {
"prompt": "ultra-wide e-commerce campaign banner, red and gold gradient background stretching horizontally, bold festive typography reading \"MID-YEAR SALE 50% OFF\" in the center, gift boxes and ribbons on both sides, flat illustration style",
"aspect_ratio": "8:1",
"resolution": "2K"
}
}Getting the result
- The response returns a taskId immediately without waiting for generation to finish.
- In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
- When status=success, download the generated image from output[].url.
- When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.
FAQ
How is pricing calculated? Do resolutions cost differently?
Billed per image, and all three resolution tiers (1K/2K/4K) cost the same — choosing 4K costs no more than 1K, so use it freely when you need high-resolution output. See the live pricing page for current rates. View live pricing
What is thinking_mode and when should I enable it?
When enabled, the model performs enhanced reasoning before generating, which typically improves composition and detail but noticeably increases generation time. HiAPI keeps it off by default; enable it for quality-critical, non-urgent jobs such as final poster renders, and keep it off for fast batch generation.
How long do generated image URLs stay valid?
Upstream image URLs and task data are kept for only 24 hours and cannot be recovered afterwards. Download results promptly after success, or use HiAPI asset storage to persist them to your own space.
Does it support Chinese prompts? How do I get the best results?
Yes. Prompts can be written in Chinese or English, with native optimization for Chinese scenes such as signage, posters and in-image Chinese text. Prompts are limited to 1-5000 characters (longer input is truncated). Structured descriptions covering subject, setting, lighting and style work best, and in-image text should be quoted verbatim.