Image Generations - AGCloud API

Authorization

Auth Type: Bearer Auth (In: header)
Format: Authorization: Bearer <YOUR_API_KEY>
Description: Use Bearer <YOUR_API_KEY>. Format: Authorization: Bearer sk-xxxxxx.
API Key: where API Key is your AGCloud API KEY

Create an image generation task with POST /sp/v1/images/generations. The response returns a task ID that you can use with the query task endpoint. The same create endpoint supports both text-to-image and image-to-image flows:

Omit image_urls to generate an image from prompt.
Provide one or more image_urls to generate or edit images from references.

Headers

Header	Required	Description
`Authorization`	✅	`Bearer <API_KEY>`
`Content-Type`	✅	Must be `application/json`.
`Idempotency-Key`	-	Idempotency key for safe retries. If omitted, the server generates one and returns it in the response header.

Idempotency-Key must match ^[A-Za-z0-9._:-]{1,128}$. Use a new idempotency key for each new task. If a request times out and you retry the same task, reuse the same key with the exact same request body. Reusing a key with a different body returns 409 idempotency_conflict.

Request Parameters

Only model and prompt are strictly required. Other fields are handled according to model capability; unsupported combinations may create a task that later reaches failed with details in error.

Field	Type	Required	Default	Description
`model`	string	✅	-	Model ID enabled for your account, for example `sp-gpt-image-2`.
`prompt`	string	✅	-	Image generation or editing prompt. Cannot be empty.
`image_urls`	string[]	-	-	Reference images. Each item supports a public HTTPS URL or a base64 image Data URL. Non-empty values enable image-to-image or image editing behavior.
`mask_url`	string	-	-	Mask image for inpainting. Usually used together with `image_urls`; supports the same URL formats.
`n`	integer	-	`1`	Number of images to generate. Usually `1` to `4`.
`size`	string	-	-	Output size, for example `1024x1024` or `2048x2048`. Supported values depend on the model.
`quality`	string	-	-	Quality tier. Supported values depend on the model.
`response_format`	string	-	-	Response format option. Supported values depend on the model.
`background`	string	-	-	Background option. Supported values depend on the model.
`input_fidelity`	string	-	-	Reference image fidelity tier. Supported values depend on the model.
`output_format`	string	-	-	Output image format. Supported values depend on the model.
`output_compression`	integer	-	-	Output compression level, usually `0` to `100`. Only applies when supported by the selected output format and model.
`user`	string	-	-	Your application-side end-user identifier.
`extra`	object	-	-	Extension parameters.
`copy`	object	-	-	Reserved marketing-copy object. May include `headline`, `subheadline`, `selling_points`, `activity_time`, and `cta`.
`brand`	object	-	-	Reserved brand object. May include `logo_url`, `primary_color`, and `secondary_color`.

Base64 Reference Images

image_urls and mask_url can contain base64 image Data URLs in this format:

data:image/<subtype>;base64,<base64 data>

Item	Rule
Image subtype	Supports `png`, `jpeg`, `jpg`, `webp`, and `gif`; case-insensitive.
Separator	Must use `;base64,`.
Encoding	Must use standard base64 with `+`, `/`, and `=`. URL-safe base64 is not supported.
Whitespace	Line breaks and spaces in the base64 payload are ignored.
Size limit	Each decoded image must be no larger than `180 MB`; the whole HTTP request body must be no larger than `256 MB`.

Create Response

Creation succeeds with 202 Accepted. The response header contains the idempotency key used for this request.

Idempotency-Key: img-20260922-001

{
  "id": "gen_5a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "object": "image.generation",
  "status": "queued",
  "model": "sp-gpt-image-2",
  "created": 1786000000
}

Field	Type	Description
`id`	string	Task ID used to query the result.
`object`	string	Always `image.generation`.
`status`	string	Usually `queued` immediately after creation.
`model`	string	Model ID used for the task.
`created`	integer	Creation time as Unix seconds.

Error Responses

Non-2xx responses use a unified error format:

{
  "error": {
    "type": "api_error",
    "code": "invalid_parameter",
    "message": "field 'model' is required"
  }
}

HTTP Status	Code	Description
`400`	`invalid_parameter`	Invalid request parameters, such as missing `model` or `prompt`, or an invalid JSON body.
`400`	`invalid_idempotency_key`	Invalid `Idempotency-Key` format.
`401`	`invalid_api_key`	API key is missing or invalid.
`402`	`insufficient_balance`	Account balance or quota is insufficient.
`403`	`model_access_denied`	Current API key cannot access the requested model.
`403`	`model_disabled`	The model is currently disabled.
`404`	`model_not_found`	The model does not exist or is not enabled for the account.
`409`	`idempotency_conflict`	The same `Idempotency-Key` was used with a different request body.
`500`	`task_store_error`	Internal task storage error.
`503`	`service_unavailable`	Service is temporarily unavailable. Retry later.

Recommended Flow

Generate a new Idempotency-Key on the client.
Call POST /sp/v1/images/generations to create a task.
Store the returned id.
Poll GET /sp/v1/images/generations/{id} on the query task page until status is terminal.

​Authorization

​Headers

​Request Parameters

​Base64 Reference Images

​Create Response

​Error Responses

​Recommended Flow