Overview
This API is used to generate or edit an image. For synchronous model calls, the result is returned directly as an image. For asynchronous tasks, the task ID is returned, which can be queried via /api/v1/tasks/{task_id}. The X-Async header is optional.
API details
Constraints
- The caller must have an API Key. For more information, see Manage AI API Keys.
Request path
POST {BASE_URL}/api/v1/images/generations
Request header
Name |
Required |
Example value |
Description |
|---|---|---|---|
| Authorization | Yes | Bearer {token} | Authentication information |
| Content-Type | No | application/json | Request body format |
| X-Async | No | Historical compatibility parameter. No configuration is required for new connections, as the service automatically determines whether to return the result synchronously or asynchronously based on the model type. This header is no longer used to forcibly switch modes. |
Request parameters
Path
Name |
Type |
Required |
Example value |
Description |
|---|---|---|---|---|
| None | This API has no path parameters. |
Query
Name |
Type |
Required |
Example value |
Description |
|---|---|---|---|---|
| None | This API has no query parameters. |
Body
Name |
Type |
Required |
Example value |
Description |
|---|---|---|---|---|
| model | string | Yes | Model name |
Vendor-specific parameters
The request parameters for image generation models vary by vendor. Refer to the corresponding vendor's documentation for detailed parameter descriptions:
- Volcanic Engine: Refer to Volcanic Engine Image Generation API Documentation
- Alibaba Cloud Bailian: Refer to Alibaba Cloud Bailian model API documentation
Response
Response parameters
Name |
Type |
Description |
|---|---|---|
| success | boolean | Whether the request was successful |
| code | string | Response code |
| message | string | Response information |
| data | object | Business response data |
data
Name |
Type |
Description |
|---|---|---|
| Depends on the specific response | unknown | Successful response data, which may include information such as the image result or task ID. |
Request example
curl --request POST '{BASE_URL}/api/v1/images/generations' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{
"model": "your-model-name"
}'
Response example
Successful response (200)
{
"success": true,
"code": "200",
"message": "successful",
"data": {
// The specific returned data depends on the model type (synchronous/asynchronous).
}
}
Request parameter error (400)
{
"success": false,
"code": "400",
"message": "Invalid request parameters"
}
Unauthorized (401)
{
"success": false,
"code": "401",
"message": "Unauthorized"
}
Excessive request frequency (429)
{
"success": false,
"code": "429",
"message": "Rate limit exceeded"
}