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
- You must have an API key. For more information, see Manage AI API keys.
Request path
POST https://ai-api-g.oceanbase.com/api/v1/images/generations
Request header
Name |
Required |
Example value |
Description |
|---|---|---|---|
| Authorization | Yes | Bearer YOUR_API_KEY | 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 | gpt-image-2 | 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:
- BytePlus ModelArk: See the BytePlus image generation API documentation.
- Alibaba Cloud Model Studio: See Image generation and editing.
Response
Response parameters
Name |
Type |
Description |
|---|---|---|
| success | boolean | Whether the request was successful |
| code | string | Response code |
| message | string | Response message. |
| data | object | 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 'https://ai-api-g.oceanbase.com/api/v1/images/generations' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "gpt-image-2"
}'
Response example
Successful response (200)
Synchronous models directly return data. Asynchronous models return task_id and task_status, which can be queried through /api/v1/tasks/{task_id}.
{
"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"
}