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

# Create image task

> 创建 GPT Image 2 异步生图任务。

Create an async GPT Image 2 task. Poll with [Query image task](/en/api-reference/images/query) and read `result.image_url` when completed.

## Models

| `model` | Notes | Billing |
| - | - | - |
| `gpt-image-2` | Preferred; pick tier via `quality` | see below |
| `gpt-image-2-low` | Low tier | `per_task` |
| `gpt-image-2-medium` | Medium tier | `per_task` |
| `gpt-image-2-high` | High tier | `per_task` |

If `model` is `gpt-image-2` and `quality` is `low` / `medium` / `high`, billing uses the matching `gpt-image-2-*` model. Default `quality` is `auto`.

## Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `model` | string | yes | See table above |
| `prompt` | string | yes | 1–4000 characters |
| `quality` | string | no | `auto` (default), `low`, `medium`, `high` |
| `n` | int | no | 1–4 images, default 1; cost × count |
| `ratio` | string | no | Aspect ratio; `size` is an alias |
| `size` | string | no | Alias of `ratio` |
| `resolution` | string | no | Optional hint (e.g. `1k` / `2k`) |
| `images` | string\[] | no | Public reference image URLs, max **15** |

## Example

```bash theme={null}
curl -X POST 'https://sigrunai.com/v1/images' \
  -H 'Authorization: Bearer sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Minimal product still life, white background, soft light",
    "quality": "medium",
    "n": 1,
    "ratio": "1:1"
  }'
```

Success response:

```json theme={null}
{
  "code": 20000,
  "msg": "提交成功",
  "data": {
    "task_id": "img_xxxxxxxx",
    "status": "queued",
    "progress": 0,
    "model": "gpt-image-2",
    "cost": 0.2,
    "result": {}
  }
}
```


## OpenAPI

````yaml POST /v1/images
openapi: 3.1.0
info:
  title: AI Platform OpenAPI
  description: >-
    Async image and video generation. Create a task, then poll task_id. Result
    URLs are kept about 3 days.
  version: 1.0.0
servers:
  - url: https://sigrunai.com
    description: AI Platform production
security:
  - bearerAuth: []
paths:
  /v1/images:
    post:
      tags:
        - Images
      summary: Create image task
      description: Create an async GPT Image 2 task.
      operationId: createImage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageCreateRequest'
            examples:
              gptImage2:
                summary: gpt-image-2
                value:
                  model: gpt-image-2
                  prompt: 极简产品静物，白色背景，柔光
                  quality: medium
                  'n': 1
                  ratio: '1:1'
      responses:
        '200':
          description: 提交成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskQueryResponse'
components:
  schemas:
    ImageCreateRequest:
      type: object
      required:
        - model
        - prompt
      properties:
        model:
          type: string
          description: gpt-image-2 或 gpt-image-2-low / medium / high
          example: gpt-image-2
        prompt:
          type: string
          minLength: 1
          maxLength: 4000
        quality:
          type: string
          enum:
            - auto
            - low
            - medium
            - high
          default: auto
        'n':
          type: integer
          minimum: 1
          maximum: 4
          default: 1
        ratio:
          type: string
        size:
          type: string
          description: ratio 别名
        resolution:
          type: string
        images:
          type: array
          items:
            type: string
            format: uri
          maxItems: 15
    TaskQueryResponse:
      type: object
      properties:
        code:
          type: integer
          example: 20000
        msg:
          type: string
        data:
          $ref: '#/components/schemas/TaskQueryData'
    TaskQueryData:
      type: object
      properties:
        task_id:
          type: string
        status:
          type: string
          description: queued / processing / completed / failed 等
        progress:
          type: integer
        model:
          type: string
        created_at:
          type: integer
        completed_at:
          type: integer
        cost:
          type: number
        error_message:
          type: string
        result:
          $ref: '#/components/schemas/TaskResult'
    TaskResult:
      type: object
      properties:
        image_url:
          type: string
        video_url:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API key from the console. Format: Bearer sk_xxx'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.