How to Use the Qwen Image 3.0 API on EvoLink
POST /v1/images/generations with model qwen-image-3.0-pro, store the returned id, then poll GET /v1/tasks/{task_id} until the task completes.Before you start
You need:
- an EvoLink account and API key
- sufficient account balance for your test
- a prompt for text-to-image, or one to three public image URLs for reference-guided editing
- a place to persist
task_id, task status, and final image URLs
| Item | Current EvoLink contract |
|---|---|
| Base URL | https://api.evolink.ai |
| Create task | POST /v1/images/generations |
| Query task | GET /v1/tasks/{task_id} |
| Model ID | qwen-image-3.0-pro |
| Modes | Text-to-image; image-to-image with 1-3 references |
| Outputs | n: 1-6 |
| Size | auto or a supported WIDTHxHEIGHT value |
| Authentication | Bearer API key |
| Processing | Asynchronous task |
Step 1: create a text-to-image task
Set your key in an environment variable. Do not hard-code it in a browser bundle or commit it to source control.
export EVOLINK_API_KEY="your_api_key"Create a task:
curl --request POST "https://api.evolink.ai/v1/images/generations" \
--header "Authorization: Bearer ${EVOLINK_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"model": "qwen-image-3.0-pro",
"prompt": "A structured annual-report cover with a clean grid, navy and white palette, precise small typography, and a photorealistic glass product in the center",
"n": 1,
"size": "1024x1024",
"prompt_extend": false,
"watermark": false
}'The initial response returns a task identifier and processing state:
{
"id": "task-unified-1772000000-a1b2c3d4",
"status": "processing"
}id immediately (use it as the {task_id} path value when polling). Do not hold the HTTP request open while generation runs.Step 2: poll the asynchronous task
Query the task until it reaches a terminal state:
curl --request GET \
"https://api.evolink.ai/v1/tasks/task-unified-1772000000-a1b2c3d4" \
--header "Authorization: Bearer ${EVOLINK_API_KEY}"A completed task includes result URLs and usage information:
{
"id": "task-unified-1772000000-a1b2c3d4",
"status": "completed",
"progress": 100,
"results": ["https://example-result-host/image_0.png"],
"usage": {
"credits_used": 5.5044,
"cost": { "credits": 5.5044, "usd": 0.0809, "cny": 0.5504 }
}
}completed, failed, and cancelled as terminal states. For a polling client, start with a short interval, increase it gradually, and enforce an overall timeout. Avoid a tight loop that adds unnecessary load without making generation faster.
Step 3: add reference images for editing
image_urls. Omit the field entirely for pure text-to-image.curl --request POST "https://api.evolink.ai/v1/images/generations" \
--header "Authorization: Bearer ${EVOLINK_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"model": "qwen-image-3.0-pro",
"prompt": "Keep the product identity and rebuild the scene as a clean editorial campaign with precise bilingual typography",
"image_urls": [
"https://your-cdn.example.com/product-reference.png"
],
"n": 2,
"prompt_extend": true
}'Use one to three input images. Make each role explicit in the prompt: which image controls the subject, which controls style, and which controls composition. A vague “combine these” instruction is harder to evaluate and reproduce.
Parameter choices that change output behavior
| Parameter | Use it for | Production guidance |
|---|---|---|
prompt | Image content, layout, text, style, constraints | Use structured sections for dense briefs; verify exact rendered copy |
image_urls | Reference-guided editing | Use stable public HTTPS URLs (base64 / data URLs are not supported); keep input files within documented limits |
n | Generate 1-6 candidates | Increase only when multiple candidates improve accepted-output cost |
size | auto or explicit output dimensions | Use an explicit size for product surfaces with fixed aspect ratios |
prompt_extend | Let the model enrich a short prompt | Disable when exact wording and layout constraints must remain unchanged |
negative_prompt | Exclude unwanted visual traits | Keep it short and specific instead of restating the positive prompt |
seed | Improve repeatability during tests | Store it with the prompt and model ID, but do not assume perfect determinism |
watermark | Add or omit the model watermark | Match your compliance and product requirements |
callback_url | Receive terminal task updates | Use HTTPS, authenticate callbacks at your application layer, and make handling idempotent |
The current EvoLink API reference is the authority for defaults and allowed values. Limited-preview upstream contracts can change, so do not copy parameter assumptions from a provider-direct SDK into the EvoLink request without checking the model page.
Polling or callback: which should you use?
Use polling for local development and low-volume tools. It is easy to debug and does not require a public webhook endpoint.
callback_url for application workflows where a worker should resume after generation completes. Your callback handler should:- return success quickly
- verify the request according to your application’s security policy
- use
task_idas an idempotency key - tolerate duplicate delivery
- fetch current task state before final business actions when necessary
- queue image download and storage instead of doing heavy work inside the webhook request
Even with callbacks, keep a reconciliation job. It can find tasks that remained in a non-terminal state because a callback was missed or your service was temporarily unavailable.
Store result images promptly
The current model documentation states that generated result links are temporary. Download accepted outputs to your own object storage instead of saving third-party result URLs as permanent application assets.
A useful result record includes:
task_id
model_id
prompt_version
input_image_ids
request_parameters
submitted_at
completed_at
terminal_status
result_storage_urls
credits_used
review_status
fallback_task_idThis record supports customer support, cost analysis, replay, and model migration.
Production retry and fallback policy
Do not retry every failure blindly. First separate failures into categories.
| Failure type | Default action | Why |
|---|---|---|
| Authentication or balance error | Stop and alert | A retry will not fix credentials or funding |
| Invalid parameter or input URL | Fix request; do not auto-retry | Repeating the same invalid payload wastes time |
| Rate limit or transient upstream error | Retry with exponential backoff and jitter | The condition may clear without changing the prompt |
| Task timeout with unknown state | Reconcile task before resubmitting | Avoid duplicate generation and duplicate spend |
| Successful image rejected by QA | Adjust prompt or route to fallback | This is a quality decision, not a transport retry |
While upstream access and capacity remain limited, keep another image model behind the same product action. A fallback should preserve the user’s original prompt and assets but adapt only the parameters required by the alternative model. Log when fallback occurs so a silent route change does not corrupt your evaluation data.
A rollout path for the first production feature
Start with one narrow job rather than exposing every parameter in a generic image generator.
Good launch candidates include:
- a report-cover or infographic generator
- multilingual ecommerce creative variants
- educational diagram drafts with mandatory human review
- product campaign layouts from one reference image
- storyboard generation from a structured creative brief
Use this rollout sequence:
- Build a fixed prompt template and a small parameter surface.
- Run internal evaluation with 20-50 representative inputs.
- Save outputs to your own storage and add reviewer states.
- Launch behind a feature flag or limited user cohort.
- Measure task success, p50/p95 latency, accepted-output rate, retries, and cost per accepted image.
- Keep a fallback until measured capacity is stable for your traffic.
FAQ
What model ID does EvoLink use for Qwen Image 3.0?
qwen-image-3.0-pro.Which endpoint creates an image task?
POST https://api.evolink.ai/v1/images/generations with your Bearer API key and JSON request body.Is the API synchronous?
task_id. Poll GET /v1/tasks/{task_id} or provide a supported HTTPS callback URL.How do I run text-to-image instead of editing?
prompt without image_urls. Add one to three image_urls only when you want reference-guided editing.How many images can one request generate?
n from 1 to 6. Evaluate whether extra candidates improve cost per accepted output before increasing batch size.Should I enable prompt extension?
prompt_extend when you want the model to enrich a short creative prompt. Disable it when exact wording, labels, and layout instructions must stay under your control.How should I store generated images?
Download accepted results to your own object storage. Do not rely on temporary generated-image URLs as permanent assets.
Is Qwen Image 3.0 ready for critical production traffic?
The EvoLink route is live, but production readiness is workload-specific while upstream access remains limited. Measure latency, failure rate, acceptance, and capacity, and keep a fallback route.
