diff --git a/apps/api/docs/swagger.json b/apps/api/docs/swagger.json
index 4f9a1ad..a8684a0 100644
--- a/apps/api/docs/swagger.json
+++ b/apps/api/docs/swagger.json
@@ -5938,6 +5938,7 @@
                         "BearerAuth": []
                     }
                 ],
+                "description": "默认同步返回 OpenAI-compatible Images 响应；设置 X-Async=true 时异步创建任务并返回 202。",
                 "consumes": [
                     "application/json"
                 ],
@@ -5957,6 +5958,12 @@
                         "schema": {
                             "$ref": "#/definitions/httpapi.TaskRequest"
                         }
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "true 时异步创建任务并返回 202",
+                        "name": "X-Async",
+                        "in": "header"
                     }
                 ],
                 "responses": {
@@ -5966,6 +5973,12 @@
                             "$ref": "#/definitions/httpapi.CompatibleResponse"
                         }
                     },
+                    "202": {
+                        "description": "Accepted",
+                        "schema": {
+                            "$ref": "#/definitions/httpapi.TaskAcceptedResponse"
+                        }
+                    },
                     "400": {
                         "description": "Bad Request",
                         "schema": {
@@ -6000,6 +6013,7 @@
                         "BearerAuth": []
                     }
                 ],
+                "description": "默认同步返回 OpenAI-compatible Images 响应；设置 X-Async=true 时异步创建任务并返回 202。",
                 "consumes": [
                     "application/json"
                 ],
@@ -6019,6 +6033,12 @@
                         "schema": {
                             "$ref": "#/definitions/httpapi.TaskRequest"
                         }
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "true 时异步创建任务并返回 202",
+                        "name": "X-Async",
+                        "in": "header"
                     }
                 ],
                 "responses": {
@@ -6028,6 +6048,12 @@
                             "$ref": "#/definitions/httpapi.CompatibleResponse"
                         }
                     },
+                    "202": {
+                        "description": "Accepted",
+                        "schema": {
+                            "$ref": "#/definitions/httpapi.TaskAcceptedResponse"
+                        }
+                    },
                     "400": {
                         "description": "Bad Request",
                         "schema": {
diff --git a/apps/api/docs/swagger.yaml b/apps/api/docs/swagger.yaml
index 2e8ccac..f48e4d3 100644
--- a/apps/api/docs/swagger.yaml
+++ b/apps/api/docs/swagger.yaml
@@ -7400,6 +7400,7 @@ paths:
     post:
       consumes:
       - application/json
+      description: 默认同步返回 OpenAI-compatible Images 响应；设置 X-Async=true 时异步创建任务并返回 202。
       parameters:
       - description: OpenAI Images 请求
         in: body
@@ -7407,6 +7408,10 @@ paths:
         required: true
         schema:
           $ref: '#/definitions/httpapi.TaskRequest'
+      - description: true 时异步创建任务并返回 202
+        in: header
+        name: X-Async
+        type: boolean
       produces:
       - application/json
       responses:
@@ -7414,6 +7419,10 @@ paths:
           description: OK
           schema:
             $ref: '#/definitions/httpapi.CompatibleResponse'
+        "202":
+          description: Accepted
+          schema:
+            $ref: '#/definitions/httpapi.TaskAcceptedResponse'
         "400":
           description: Bad Request
           schema:
@@ -7439,6 +7448,7 @@ paths:
     post:
       consumes:
       - application/json
+      description: 默认同步返回 OpenAI-compatible Images 响应；设置 X-Async=true 时异步创建任务并返回 202。
       parameters:
       - description: OpenAI Images 请求
         in: body
@@ -7446,6 +7456,10 @@ paths:
         required: true
         schema:
           $ref: '#/definitions/httpapi.TaskRequest'
+      - description: true 时异步创建任务并返回 202
+        in: header
+        name: X-Async
+        type: boolean
       produces:
       - application/json
       responses:
@@ -7453,6 +7467,10 @@ paths:
           description: OK
           schema:
             $ref: '#/definitions/httpapi.CompatibleResponse'
+        "202":
+          description: Accepted
+          schema:
+            $ref: '#/definitions/httpapi.TaskAcceptedResponse'
         "400":
           description: Bad Request
           schema:
diff --git a/apps/api/internal/httpapi/handlers.go b/apps/api/internal/httpapi/handlers.go
index 0079946..2a69032 100644
--- a/apps/api/internal/httpapi/handlers.go
+++ b/apps/api/internal/httpapi/handlers.go
@@ -1267,12 +1267,15 @@ func openAIEmbeddingsDoc() {}
 
 // openAIImagesDoc godoc
 // @Summary 创建或编辑 OpenAI Images
+// @Description 默认同步返回 OpenAI-compatible Images 响应；设置 X-Async=true 时异步创建任务并返回 202。
 // @Tags images
 // @Accept json
 // @Produce json
 // @Security BearerAuth
 // @Param input body TaskRequest true "OpenAI Images 请求"
+// @Param X-Async header bool false "true 时异步创建任务并返回 202"
 // @Success 200 {object} CompatibleResponse
+// @Success 202 {object} TaskAcceptedResponse
 // @Failure 400 {object} OpenAIErrorEnvelope
 // @Failure 401 {object} OpenAIErrorEnvelope
 // @Failure 429 {object} OpenAIErrorEnvelope