POST /v1/images/generations — Create an image generation taskGET /v1/images/generations/{task_id} — Query a single taskGET /v1/images/generations — Query the task list
POST {CMR_BASE_URL}/v1/images/generationsGET {CMR_BASE_URL}/v1/images/generations/{task_id}GET {CMR_BASE_URL}/v1/images/generations
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. |
# ① 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 expiredcurl --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
import osimport timeimport requestsbase_url = os.environ["CMR_BASE_URL"]headers = {"Authorization": f"Bearer {os.environ['CMR_API_KEY']}","Content-Type": "application/json",}# ① Create a taskresp = 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 resultif task["status"] == "completed":image = task["result"]["data"][0]print(image.get("url") or image.get("b64_json"))else:print(task["error"])
POST /v1/images/generations
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. |
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.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.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. |
{"model": "cmr-image","contents": [{ "type": "text", "text": "A Shiba Inu wearing sunglasses sits on a surfboard, realistic style" }],"size": "1536x1024"}
{"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"}
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 | See task status |
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. |
{"id": "imgtask_01JQ8ZC3M9X7YB2KDVF6AHRW5B","object": "image","status": "in_progress","model": "cmr-image","created_at": 1789000000,"completed_at": null,"expires_at": 1789086400,"error": null}
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.{"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.GET /v1/images/generations/{task_id}
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.Parameter | Type | Returned or Not | Description |
id | string | Yes | Task ID |
object | string | Yes | Fixed to image |
status | string | Yes | |
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. |
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. |
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 |
{"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"}}}
GET /v1/images/generations
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. |
offset is not supported.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. |
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.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. |
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.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.b64_json, the image content is saved with the task until expires_at (24 hours after creation).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.{"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. |
failed. When the call times out, it is marked as expired.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. |
Was this page helpful?
You can also Contact sales or Submit a Ticket for help.
Help us improve! Rate your documentation experience in 5 mins.
Feedback