alibaba/
Image to ImageAlibaba's Z-Image Turbo ControlNet generates pictures that match the structure of an edge, depth or pose guide. Keeps layouts, silhouettes and poses intact for character art, product scenes and architecture, with canny, depth or pose preprocessing, control strength and start/end timing.
More settings (10)
Fill in the required parameters marked * and check number formats.
$0.0065 / megapixel · billed by each image's actual pixels
A single leopard, its spotted golden coat detailed with black rosettes, cautiously peeks its head through dense green foliage. The leopard’s eyes are alert and focused forward, ears perked, whiskers slightly visible. The bushes consist of thick, leafy shrubs with varying shades of green, some leaves partially obscuring the leopard’s muzzle and forehead. Soft natural daylight filters through the canopy above, casting dappled shadows across the animal’s fur and surrounding leaves. The composition is a medium close-up, centered on the leopard’s head emerging from the undergrowth, with shallow depth of field blurring the background vegetation.
Pricing
Unit price $0.0065 / megapixel
Billed by the actual pixels of each image; larger sizes and more images cost more. 1024×1024 is about 1 megapixel.
Each request temporarily reserves $0.013; you are charged for actual usage, usually within a minute: any unused amount is released and any usage above it is charged to your balance, even if that takes it below zero; while your balance is below zero, new requests are paused until a top-up covers it.
Failed generations are not charged.
API
Submit generation requests with this model ID.
/v1/model-tasksalibaba/z-image-turbo-controlnet/image-to-image{
"model": "alibaba/z-image-turbo-controlnet/image-to-image",
"input": {
"prompt": "A single leopard, its spotted golden coat detailed with black rosettes, cautiously peeks its head through dense green foliage. The leopard’s eyes are alert and focused forward, ears perked, whiskers slightly visible. The bushes consist of thick, leafy shrubs with varying shades of green, some leaves partially obscuring the leopard’s muzzle and forehead. Soft natural daylight filters through the canopy above, casting dappled shadows across the animal’s fur and surrounding leaves. The composition is a medium close-up, centered on the leopard’s head emerging from the undergrowth, with shallow depth of field blurring the background vegetation.",
"image_url": "<image_url>"
}
}Input schema
| Parameter | Type | Requirement | Default |
|---|---|---|---|
| image_url | string | Required | — |
| prompt | string | Required | — |
| acceleration | string | Optional | regular |
| control_end | number | Optional | 0.8 |
| control_scale | number | Optional | 0.75 |
| control_start | number | Optional | 0 |
| enable_prompt_expansion | boolean | Optional | false |
| image_size | object | string | Optional | auto |
| num_images | integer | Optional | 1 |
| num_inference_steps | integer | Optional | 8 |
| output_format | string | Optional | png |
| preprocess | string | Optional | none |
| seed | integer | Optional | — |
Response
The API returns a result or a pollable asynchronous task. See the examples and Schema below for the response mode and result fields.
Code examples
Async submission returns a task ID. Poll until status is completed, then retrieve the generated content from the result. Get your API key in the console.
# Use a new directory for each new generation. Rerunning here continues this task.
set -eu
test -s model-task-id.txt || python3 -c "import uuid; print(uuid.uuid4())" > model-task-id.txt
REQUEST_ID=$(cat model-task-id.txt)
# Idempotent: resending the same bytes with the same ID never charges twice.
curl --fail-with-body --retry 3 --retry-connrefused --request POST 'https://api.musespan.com/v1/model-tasks' \
--header "Authorization: Bearer $MUSESPAN_API_KEY" \
--header "X-Request-Id: $REQUEST_ID" \
--header "Content-Type: application/json" \
--data '{"model":"alibaba/z-image-turbo-controlnet/image-to-image","input":{"prompt":"A single leopard, its spotted golden coat detailed with black rosettes, cautiously peeks its head through dense green foliage. The leopard’s eyes are alert and focused forward, ears perked, whiskers slightly visible. The bushes consist of thick, leafy shrubs with varying shades of green, some leaves partially obscuring the leopard’s muzzle and forehead. Soft natural daylight filters through the canopy above, casting dappled shadows across the animal’s fur and surrounding leaves. The composition is a medium close-up, centered on the leopard’s head emerging from the undergrowth, with shallow depth of field blurring the background vegetation.","image_url":"<image_url>"}}'
# Poll every 5 seconds for up to 25 minutes until status is completed or failed.
# Still queued (with queue_position) 5 minutes after submission: failed with queue_timeout, not charged.
# No result 15 minutes after acceptance (or no confirmation 15 minutes after submission): failed with generation_timeout, not charged.
# Any failure is final: generate again in a new directory (a new X-Request-Id).
# A 404 means the POST did not arrive: rerun this script to resend it with the same ID.
curl --fail-with-body 'https://api.musespan.com/v1/model-tasks/'"$REQUEST_ID"'' --header "Authorization: Bearer $MUSESPAN_API_KEY"