> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keevx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create image generation task

> Generate one or more AI images based on a text prompt and optional reference images. Returns a list of task IDs for polling.

## Callback Notification

After the video generation task is processed, the service will send a **POST** request to the `callback_url` provided in the initiation request.

### Structure

<ResponseField name="code" type="integer">
  Response status code. `0` indicates a successful callback transmission.
</ResponseField>

<ResponseField name="msg" type="string">
  Response message, usually "ok".
</ResponseField>

<ResponseField name="task_type" type="string">
  The type of the task. Enum: `image_generate`.
</ResponseField>

<ResponseField name="data" type="object">
  The payload containing the generation results.

  <Expandable title="Show properties">
    <ResponseField name="task_id" type="string">
      The unique identifier for the video generation task.
    </ResponseField>

    <ResponseField name="status" type="string">
      The execution status of the task. Enum: `SUCCEEDED`, `FAILED`.
    </ResponseField>

    <ResponseField name="video_url" type="string">
      The URL to access/download the generated video (valid when status is SUCCEEDED).
    </ResponseField>

    <ResponseField name="thumbnail_url" type="string">
      The URL of the generated video's thumbnail/cover image.
    </ResponseField>

    <ResponseField name="error_message" type="string">
      Detailed error information if the task status is FAILED.
    </ResponseField>
  </Expandable>
</ResponseField>

### Callback Example

```json theme={null}
{
    "code": 0,
    "msg": "ok",
    "task_type": "image_generate",
    "data": {
        "task_id": "i2is-18e830d27ea041658e4accd576ea7008",
        "status": "SUCCEEDED",
        "image_url": "https://storage.googleapis.com/xiling_us_central1_bucket/backend-saas-cdn/video-ai/image2image/10d88def-623d-4974-858a-b8c0ddfe2d1d-i2is-18e830d27ea041658e4accd576ea7008-process.png",
        "error_message": ""
    }
}
```


## OpenAPI

````yaml POST /v1/image_generate
openapi: 3.1.1
info:
  title: OpenAPI Plant Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.keevx.com/
security:
  - bearerAuth: []
paths:
  /v1/image_generate:
    post:
      summary: Submit an image generation task
      description: >-
        Generate one or more AI images based on a text prompt and optional
        reference images. Returns a list of task IDs for polling.
      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: Task submitted successfully, or a business-level error occurred.
          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: Successful submission
                  value:
                    code: 0
                    msg: ok
                    data:
                      task_ids:
                        - i2is-a1b2c3d4e5f6
                        - i2is-g7h8i9j0k1l2
                imageProcessingError:
                  summary: Image processing error (code 530002)
                  value:
                    code: 530002
                    msg: download reference image failed
                taskCreationError:
                  summary: Task creation error (code 530003)
                  value:
                    code: 530003
                    msg: create task failed
        '400':
          description: Request parameter validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              examples:
                bindingError:
                  summary: JSON binding error (code 100001)
                  value:
                    code: 100001
                    msg: >-
                      Key: 'ApiSubmitImageToImageRequest.Prompt' Error:Field
                      validation for 'Prompt' failed on the 'required' tag
                validationError:
                  summary: Parameter validation error (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: Text prompt for image generation (required).
        reference_images:
          type: array
          items:
            type: string
            format: uri
          maxItems: 5
          description: >-
            Optional list of reference image URLs. Max 5 images, each under
            20MB. Supported formats: JPG, JPEG, PNG, BMP, WebP, GIF. Excess
            items are silently truncated to 5.
        module:
          type: string
          enum:
            - std
            - pro
          default: std
          description: >-
            Generation mode. `std` = Standard Model (default), `pro` = Pro
            Model.
        generate_count:
          type: integer
          minimum: 1
          maximum: 8
          default: 1
          description: Number of images to generate. Each produces a separate task ID.
        image_quality:
          type: string
          enum:
            - 1K
            - 2K
            - 4K
          default: 2K
          description: Output image quality / resolution tier.
        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: Output image aspect ratio.
    BaseResponse:
      type: object
      required:
        - code
        - msg
      properties:
        code:
          type: integer
          description: >-
            Business status code. `0` indicates success; non-zero indicates an
            error.
        msg:
          type: string
          description: Status message. `ok` on success; error description on failure.
        data:
          description: Business data payload. Omitted or null on error responses.
    SubmitImageGenerateData:
      type: object
      required:
        - task_ids
      properties:
        task_ids:
          type: array
          items:
            type: string
          description: >-
            List of sub-task IDs, one per generated image. Count equals
            `generate_count`. Poll each ID individually via the GET endpoint.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````