> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keevx.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# 创建图片创作任务
> 根据文本提示词和可选的参考图片，生成一张或多张 AI 图片。返回任务 ID 列表用于轮询查询。
## 回调通知
视频生成任务处理完成后，服务将向发起请求中提供的 `callback_url` 发送一个 **POST** 请求。
### 结构
响应状态码。`0` 表示回调发送成功。
响应消息，通常为 "ok"。
任务类型。枚举值：`image_to_video`。
包含生成结果的数据载体。
视频生成任务的唯一标识符。
任务的执行状态。枚举值：`SUCCEEDED`、`FAILED`。
生成视频的访问/下载链接（当 status 为 SUCCEEDED 时有效）。
生成视频的缩略图/封面图链接。
当任务状态为 FAILED 时的详细错误信息。
### 回调示例
```json theme={null}
{
"code": 0,
"msg": "ok",
"task_type": "image_generate",
"data": {
"task_id": "i2is-18e830d27ea041658e4accd576ea7008",
"status": "SUCCEEDED",
"image_url": "https://xiling-dh.bj.bcebos.com/f4231c3b-fa87-4930-90e3-29fcdcdd2759-i2is-f32d314204d64e75b9e13034ad3443d5-ai.png",
"error_message": ""
}
}
```
## OpenAPI
````yaml POST /v1/image_generate
openapi: 3.1.1
info:
title: Keevx API
description: Keevx AI API，提供图片生成、图生视频和视频翻译服务。
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.keevx.cn/
security:
- bearerAuth: []
paths:
/v1/image_generate:
post:
summary: 提交图片生成任务
description: 根据文本提示词和可选的参考图片，生成一张或多张 AI 图片。返回任务 ID 列表用于轮询查询。
operationId: submitImageGenerate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitImageGenerateRequest'
example:
prompt: A serene mountain lake at sunset with golden reflections
reference_images:
- https://example.com/ref.jpg
module: std
generate_count: 2
image_quality: 2K
image_ratio: '16:9'
responses:
'200':
description: 任务提交成功，或发生业务级错误。
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
properties:
data:
$ref: '#/components/schemas/SubmitImageGenerateData'
- $ref: '#/components/schemas/BaseResponse'
examples:
success:
summary: 提交成功
value:
code: 0
msg: ok
data:
task_ids:
- i2is-a1b2c3d4e5f6
- i2is-g7h8i9j0k1l2
imageProcessingError:
summary: 图片处理错误 (code 530002)
value:
code: 530002
msg: download reference image failed
taskCreationError:
summary: 任务创建错误 (code 530003)
value:
code: 530003
msg: create task failed
'400':
description: 请求参数校验失败。
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
examples:
bindingError:
summary: JSON 绑定错误 (code 100001)
value:
code: 100001
msg: >-
Key: 'ApiSubmitImageToImageRequest.Prompt' Error:Field
validation for 'Prompt' failed on the 'required' tag
validationError:
summary: 参数校验错误 (code 100002)
value:
code: 100002
msg: 'generate_count should be [1,8], current: 10'
components:
schemas:
SubmitImageGenerateRequest:
type: object
required:
- prompt
properties:
prompt:
type: string
maxLength: 1000
description: 图片生成的文本提示词（必填）。
reference_images:
type: array
items:
type: string
format: uri
maxItems: 5
description: >-
可选的参考图片 URL 列表。最多 5 张，每张不超过
20MB。支持格式：JPG、JPEG、PNG、BMP、WebP、GIF。超出部分会被静默截断为 5 张。
module:
type: string
enum:
- std
- pro
default: std
description: 生成模式。`std` = 标准模式（默认），`pro` = 专业模式。
generate_count:
type: integer
minimum: 1
maximum: 8
default: 1
description: 生成图片数量。每张图片会产生一个独立的任务 ID。
image_quality:
type: string
enum:
- 1K
- 2K
- 4K
default: 2K
description: 输出图片质量/分辨率等级。
image_ratio:
type: string
enum:
- '1:1'
- '3:2'
- '2:3'
- '3:4'
- '4:3'
- '4:5'
- '5:4'
- '9:16'
- '16:9'
- '21:9'
default: '9:16'
description: 输出图片宽高比。
BaseResponse:
type: object
required:
- code
- msg
properties:
code:
type: integer
description: 业务状态码。`0` 表示成功；非零表示错误。
msg:
type: string
description: 状态消息。成功时为 `ok`；失败时为错误描述。
data:
description: 业务数据。错误响应时省略或为 null。
SubmitImageGenerateData:
type: object
required:
- task_ids
properties:
task_ids:
type: array
items:
type: string
description: 子任务 ID 列表，每张生成的图片对应一个。数量等于 `generate_count`。通过 GET 接口逐个轮询每个 ID。
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````