tencent cloud

Image Generation Models

Download
Focus Mode
Font Size
Last updated: 2026-11-17 14:27:53
AI-Translated & Reviewed

Overview

CMR Image API generates images based on text prompts and optional reference images and masks, and is suitable for scenarios such as poster and asset creation and image editing. You only need to use the unified API and CMR API Key to call image generation models from different vendors. After submission, wait within the waiting window configured for the instance: if the instance reaches a terminal state within the window, the response directly includes the result. Otherwise, a task ID is returned, and you can poll through the query API. Text-to-image and image editing use the same creation API. Related operations use the following APIs:
POST /v1/images/generations — Create an image generation task
GET /v1/images/generations/{task_id} — Query a single task
GET /v1/images/generations — Query the task list

Prerequisites

1. It is recommended to read Usage Constraints and Supported Model Providers in advance for relevant information.
2. A CMR instance has been created. For detailed instructions, see Creating a CMR Instance.
3. A BYOK instance has been created. For detailed instructions, see Creating a BYOK Instance.
4. A CMR API key has been created. For detailed instructions, see Creating a CMR API Key.
5. Image generation model association and CMR policy configuration have been completed. For detailed instructions, see Configuring Model Scheduling Management.

API Endpoint and Authentication

Request URL

POST {CMR_BASE_URL}/v1/images/generations
GET {CMR_BASE_URL}/v1/images/generations/{task_id}
GET {CMR_BASE_URL}/v1/images/generations
CMR_BASE_URL is the instance access address displayed in the console. Use the CMR model name and CMR API Key for requests. You do not need to provide the vendor's API address or API Key.

Request Header

Header
Required
Description
Authorization
Yes
Bearer <CMR_API_KEY>
Content-Type
Yes
Fixed as application/json upon submission.
X-User-Id
No
End user identifier, passed to models that support abuse tracking. Do not include it in the request body.
Idempotency-Key
No
Passed to models that support idempotency keys. CMR does not deduplicate based on this key, and resubmission creates a new task.

Quick Start

Replace the access address, API Key, and model name in the example with your own configuration.

cURL

# ① Create a task (the response already contains the result if completed within the window)
curl --request POST "${CMR_BASE_URL}/v1/images/generations" \\
--header "Authorization: Bearer ${CMR_API_KEY}" \\
--header "Content-Type: application/json" \\
--data '{
"model": "cmr-image",
"contents": [
{ "type": "text", "text": "A Shiba Inu wearing sunglasses sits on a surfboard, realistic style" }
],
"size": "1536x1024"
}'
# → {"id":"imgtask_01JQ8ZC3M9X7YB2KDVF6AHRW5B","status":"in_progress","error":null}

# ② Poll the task status until the status is completed, failed, or expired
curl --request GET "${CMR_BASE_URL}/v1/images/generations/imgtask_01JQ8ZC3M9X7YB2KDVF6AHRW5B" \\
--header "Authorization: Bearer ${CMR_API_KEY}"

# ③ After status=completed, retrieve the image from result.data[0].url or result.data[0].b64_json

Python

import os
import time
import requests

base_url = os.environ["CMR_BASE_URL"]
headers = {
"Authorization": f"Bearer {os.environ['CMR_API_KEY']}",
"Content-Type": "application/json",
}

# ① Create a task
resp = requests.post(
f"{base_url}/v1/images/generations",
headers=headers,
json={
"model": "cmr-image",
"contents": [
{"type": "text", "text": "A Shiba Inu wearing sunglasses sits on a surfboard, realistic style"}
],
"size": "1536x1024",
},
timeout=120,
)
resp.raise_for_status()
task = resp.json()

# ② Poll when not in a terminal state (recommended interval: 2 seconds or more)
while task["status"] in ("queued", "in_progress"):
time.sleep(2)
task = requests.get(
f"{base_url}/v1/images/generations/{task['id']}",
headers=headers,
timeout=30,
).json()

# ③ Obtain the result
if task["status"] == "completed":
image = task["result"]["data"][0]
print(image.get("url") or image.get("b64_json"))
else:
print(task["error"])

Creating a Task

POST /v1/images/generations

Request Parameters

Parameter
Type
Required
Description
model
string
Yes
CMR model name. Available values are subject to the console.
contents
array
No
Prompts and images. See Material Structure. Contains at least one type=text element. Use either this parameter or prompt.
prompt
string
No
A single prompt that CMR converts into a text content. If it appears together with contents, a 400 error is returned.
n
integer
No
Number of images to generate independently. The value must be greater than or equal to 1. If not specified, 1 image is submitted by default. This is not the upper limit for the number of images in a set. The model determines its own upper limit.
size
string
No
Exact pixels: auto or width x height (for example, 1536x1024). Mutually exclusive with resolution.
aspect_ratio
string
No
Aspect ratio: auto or width:height (for example, 3:2). When specified together with exact pixels, the ratio must be consistent (21:9 and 7:3 are considered consistent).
resolution
string
No
Levels: 512, 1K, 1.5K, 2K, 3K, 4K, 1080p. Case-insensitive. 2K is not equal to 2048×2048.
quality
string
No
auto,low,medium,high,xhigh,max
background
string
No
auto, opaque, transparent. If transparent and jpeg are specified together, a 400 error is returned.
output_format
string
No
png, jpeg, webp. jpg is processed as jpeg.
output_compression
integer
No
0 to 100. Applies to JPEG and WebP.
response_format
string
No
Desired delivery format: url or b64_json. Whether the model can return results in this format depends on the model.
seed
integer
No
Random seed. The value must be greater than or equal to 0. If 0 is specified, it is submitted as-is.
negative_prompt
string
No
Content that is not expected to appear (subject to model support)
watermark
boolean
No
Whether to add a watermark (subject to model support)
moderation
string
No
auto or low
input_fidelity
string
No
Reference image fidelity: high or low. A reference image is required.
user
string
No
End user identifier, used for auditing. It is independent of the X-User-Id request header.
continuation
string | object | array
No
The result.continuation from the previous result, returned as-is. It must be non-empty and no larger than 10 MB after serialization.
Parameter Values and Model Capabilities: Whether an optional parameter takes effect depends on the selected model. Except for n, which defaults to 1 when not specified, and image role, which defaults to the reference image when not specified, CMR does not automatically fill default values for unspecified optional parameters. Standard fields cannot be set to null.
When size is specified as a tier or ratio, it is reinterpreted: size: "2K" is treated as resolution, and size: "16:9" is treated as aspect_ratio. If the reinterpreted value conflicts with an already specified field, 400 is also returned.
stream can only be omitted or set to false. If image, images, mask, async, wait, operation, provider_extra, safety_user_id, idempotency_key, or n_explicit appears at the top level, 400 is returned. extra_body, extra_headers, extra_query, and timeout are removed, and vendor parameters are specified at the top level.

Material Structure

contents are preserved in array order. If no image is provided, the request is for text-to-image generation. If an image is provided, the request is for editing or reference-based generation. There is no separate operation type field. /v1/images/edits is not provided.
Type
Format
Description
Text
{"type":"text","text":"..."}
Prompt. At least one per task; multiple prompts are concatenated with line breaks in order.
Figure
{"type":"image","role":"reference" | "mask","url":"...","id":"..."}
role defaults to reference. url must be an HTTPS URL or data:image/<type>;base64,...; HTTP and raw base64 are not accepted. id is optional and must be unique within the same request.
Mask
An image whose role is mask
At most one, and it must be accompanied by a reference. Ignore it if the model does not support it.

Request Example

Text-to-image:
{
"model": "cmr-image",
"contents": [
{ "type": "text", "text": "A Shiba Inu wearing sunglasses sits on a surfboard, realistic style" }
],
"size": "1536x1024"
}
Reference image editing:
{
"model": "cmr-image",
"contents": [
{ "type": "text", "text": "Change the sofa to dark green velvet and keep the lighting unchanged" },
{ "type": "image", "role": "reference", "url": "https://example.com/room.jpg", "id": "room" }
],
"size": "1536x1024"
}

Response Parameters

The response body is the same as the task object returned by the Query Task operation.
Parameter
Type
Returned or Not
Description
id
string
Yes
Task ID, in the format of imgtask_ plus 26 characters
object
string
Yes
Fixed to image
status
string
Yes
model
string
Yes
Name of the CMR model used in the request
created_at
integer
Yes
Creation time, Unix timestamp in seconds
completed_at
integer | null
Yes
Time when the task reaches a final state; null if not in a final state.
expires_at
integer
Yes
Task retention deadline, 24 hours after creation. After this period, queries return 404. This is not the expiration time of the image URL.
error
object | null
Yes
Reason for failure or timeout; null for success and in-progress states. See Error Response for details.
result
object | null
No
Returned only in final states. The value is the result for completed, and null for failed or expired. This field is not returned while the task is in progress. See Query Task for details.
Scenario
HTTP
Response time
Generated successfully within the window
200
status=completed, with result
Generation failed within the window or the result cannot be saved.
200
status=failed or expired, result is null, and the cause is in error
Still generating, or the waiting window is 0.
202
status=in_progress, without result
Invalid parameters, or the model call within the window is rejected.
4xx / 5xx
Error object without a task ID. If a task is created, it is marked as failed (expired for call timeout), and can be found in the list.

Response Example

{
"id": "imgtask_01JQ8ZC3M9X7YB2KDVF6AHRW5B",
"object": "image",
"status": "in_progress",
"model": "cmr-image",
"created_at": 1789000000,
"completed_at": null,
"expires_at": 1789086400,
"error": null
}
The wait window is configured by the instance ImageConfig.WaitSeconds, with a value range of 0 to 300 seconds and a default of 15 seconds. It cannot be modified by the request. When set to 0, 202 is returned immediately. The returned id only indicates that the task has been accepted. To check whether an image is already available, see status.

Provider Custom Parameters

Parameter conversion is enabled by default for a CMR instance, and vendor-defined parameters are passed through by default. Place parameters in the request as required by the vendor. You do not need to configure allowlisting for each parameter. If parameter filtering rules are configured for the instance, parameters are processed according to those rules.
For example, when the selected model uses a separate field to control image grouping, you can make the request as follows:
{
"model": "cmr-image",
"contents": [
{ "type": "text", "text": "Four angles of the same Shiba Inu" }
],
"sequential_image_generation": "auto",
"sequential_image_generation_options": { "max_images": 4 }
}
n remains an independent number of images, and CMR does not rewrite it into the vendor's image grouping field. To set default values, modify parameter values, or filter fields, you can configure rules in the parameter conversion configuration of the target CMR instance. When configuring through the management API, use CreateParamTranslationConfig to save and TestParamTranslationConfig to preview. For the image generation rule endpoint, specify images_create (for query, use images_retrieve; for list, use images_list). The names, tiers, and values of custom parameters are subject to the vendor documentation. After changing the model or vendor, confirm that these parameters still apply.

Querying a Task

GET /v1/images/generations/{task_id}
The path parameter task_id is the id returned at creation. No request body is used. If the task exists, the HTTP status code is always 200. An in-progress asynchronous task checks its status with the model. A query made less than 2 seconds after the last save directly returns the saved status. Each query counts toward the per-minute request limit, and 429 is returned when rate limiting occurs. Tasks that belong to a different Key, tasks that do not exist, and tasks older than 24 hours all return 404.

Response Parameters

Basic fields:
Parameter
Type
Returned or Not
Description
id
string
Yes
Task ID
object
string
Yes
Fixed to image
status
string
Yes
Task status. See Task status.
created_at
integer
Yes
Task creation time, Unix timestamp in seconds
completed_at
integer | null
Yes
Time when the task reaches a final state; null if not in a final state.
expires_at
integer
Yes
Task retention deadline, 24 hours after creation
model
string
Yes
Model name in the creation request
error
object | null
Yes
Failure reason; null for success and in-progress states.
result
object | null
No
Returned only in final states. The value is the result for completed, and null for failed or expired.
Task failure: If the query API itself fails (for example, the task does not exist or you do not have permission), a unified error format is returned. Task generation failure is a task attribute rather than a request failure -- the query still returns HTTP 200, and the failure reason is in the error field.
result (only when status=completed):
Parameter
Type
Returned or Not
Description
result.created
integer
Yes
Result time, Unix timestamp in seconds
result.data
array
Yes
Successfully generated images
result.errors
array
Yes
Errors when some images fail. The fields are the same as error and can include index. When all images succeed, the value is []. The task can still be completed.
result.background
string
No
Background actually used by the model
result.quality
string
No
Quality actually used by the model
result.size
string
No
Size actually used by the model. This field may not be returned when images have different sizes.
result.output_format
string
No
Encoding actually used by the model
result.provider_details
object
No
Additional content returned by the model. The structure is subject to the model.
result.continuation
string | object | array
No
Content returned for multi-round modifications. In the next round, it is placed unchanged into the request's continuation.
result.usage
object
No
Usage. If it cannot be determined, this field is not returned.
result.data[]:
Parameter
Type
Returned or Not
Description
result.data[].index
integer
Yes
Index of this image in the current result, starting from 0
result.data[].url
string | null
Yes
Image URL. null if not returned by the model.
result.data[].b64_json
string | null
Yes
Image base64. null if not returned by the model. A successful image contains at least one of url or b64_json.
result.data[].expires_at
integer
No
Expiration time of the image provided by the model
result.data[].revised_prompt
string
No
Prompt revised by the model
result.data[].size
string
No
Size of the image
result.data[].output_format
string
No
Encoding of the image
result.data[].provider_details
object
No
Additional fields of the image, such as the watermark image URL.
Usage result.usage (items not provided by the model are not returned and are not padded with 0):
Parameter
Type
Returned or Not
Description
result.usage.input_tokens
integer
No
Input tokens reported by the model
result.usage.output_tokens
integer
No
Output tokens reported by the model
result.usage.total_tokens
integer
No
Total tokens reported by the model. CMR does not populate this field by adding input and output tokens.
result.usage.input_images
integer
No
Number of reference images, excluding masks
result.usage.generated_images
integer
No
Number of actually delivered images (items with url or b64_json)
result.usage.resolution
string
No
Billing levels: 512, 1k, 1.5k, 2k, 2.5k, 3k, 3.5k, 4k. The nearest level is selected based on the generated image area, and this is not the same value table as the requested resolution.
result.usage.provider_details
object
No
Additional fields in model usage

Response Example

{
"id": "imgtask_01JQ8ZC3M9X7YB2KDVF6AHRW4T",
"object": "image",
"status": "completed",
"created_at": 1789000000,
"completed_at": 1789000012,
"expires_at": 1789086400,
"model": "cmr-image",
"error": null,
"result": {
"created": 1789000012,
"data": [
{
"index": 0,
"url": "https://upstream.example.com/out.png",
"b64_json": null,
"size": "1536x1024",
"output_format": "png"
}
],
"errors": [],
"usage": {
"input_tokens": 18,
"output_tokens": 4160,
"total_tokens": 4178,
"input_images": 0,
"generated_images": 1,
"resolution": "1.5k"
}
}
}

Queries the task list

GET /v1/images/generations
Only saved records are read. The status is not checked with the model, and images are not returned. Tasks that have already obtained results within the window are also included in the list. Only tasks of the current API Key are returned.

Request Parameters

Parameter
Type
Description
status
string
Filter by status: queued, in_progress, completed, failed, expired
model
string
Filter by exact model name used at creation
limit
integer
Number of items per page. Value range: 1-100. Default value: 20
cursor
string
The next_cursor returned on the previous page, passed back as-is. If it cannot be parsed, 400 is returned.
Tasks are sorted by creation time in descending order. offset is not supported.

Response Parameters

Parameter
Type
Description
object
string
Fixed to list
data
array
Task list. Each item contains id, object, status, model, created_at, completed_at, expires_at, and error, excluding result.
has_more
boolean
Whether there are earlier tasks
next_cursor
string | null
Cursor for the next page. It is null when there is no next page.
When has_more is true, include cursor=<next_cursor> in the next request. To retrieve images, query a single task by id. List operations do not count toward the per-minute request limit.

Task Status

Status
Description
queued
The queued value in the status enumeration. Lists can be filtered by it. The status written after the current request is accepted is in_progress.
in_progress
In progress. This status has no result.
completed
Generated successfully, and result is available.
failed
Generation failed. For the reason, see error. This includes content moderation rejection, oversized result (result_too_large), task interruption (interrupted), and unrecognizable model response (upstream_error, unknown_status).
expired
Not completed within the task time limit, which defaults to 10 minutes. error.code is task_timeout. This is not the same as the 24-hour retention period.
Status only moves forward. Terminal states (completed / failed / expired) no longer change. A polling interval of at least 2 seconds is recommended. Tasks can no longer be queried 24 hours after creation.

Result Address Description

result.data[].url is a temporary download URL on the model side. The validity period varies by vendor. Download and store the file as soon as possible after the task is completed.
When the model returns b64_json, the image content is saved with the task until expires_at (24 hours after creation).
The expires_at of a task is the record retention deadline, not the URL expiration time. If the model returns result.data[].expires_at, use that field as the authoritative value.
Access fails after the URL expires, and CMR does not reissue the address.

Error Response

When a request fails, CMR returns a unified error format:
{
"error": {
"message": "size and resolution are mutually exclusive",
"type": "invalid_request_error",
"param": "size",
"code": "invalid_parameter"
}
}
Parameter
Description
error.message
Error description. For errors from the model side, keep the original text.
error.type
Error type
error.param
Related request parameter. It is null when it cannot be located.
error.code
Error code. Subject to the actual response.
This type of response does not contain a task ID. Parameter errors, authentication failures, exceeding the limit of in-flight tasks, and insufficient replica capacity occur before task creation and do not leave a task behind. When the model call itself fails within the window, the task is marked as failed. When the call times out, it is marked as expired.
Common Error Codes
HTTP
type
code
Scenario and Handling Suggestion
400
invalid_request_error
invalid_parameter
Missing fields, incorrect types, conflicts between size and resolution, invalid masks, or cursors that cannot be parsed (invalid_cursor). Correct the issue based on error.param.
400
invalid_request_error
unsupported_parameter
stream is not false. Remove this field.
401
authentication_error
unauthorized
The API Key is invalid. Check CMR_API_KEY.
403
permission_error
forbidden
The Key has no instance assignment or no access permission.
404
not_found_error
task_not_found
The task does not exist, does not belong to the current Key, or has exceeded 24 hours. For editing, use the create API instead and include the image in contents; /v1/images/edits returns 404.
429
rate_limit_error
rate_limit_exceeded
The number of in-flight tasks reaches the RPM limit configured for the Key, user group, or instance, or the number of queries reaches the per-minute limit. Reduce the rate and retry. If the submission is rejected, the response may include x-ratelimit-*-image_tasks.
502
api_error
upstream_error
The content returned by the model cannot be recognized, or the model reports a failure. Retry later. If failures persist, use the list to find the task and contact support.
503
api_error
server_overloaded
The current replica capacity is full, and no task was created this time. Retry according to Retry-After.
503
api_error
storage_unavailable
Task storage is unavailable. Retry later.

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback