Merge pull request TQZHR#43 from lijirou12/codex/migrate-imagine-to-grok-superimage-1.0-hr1q8r

feat: expose grok-superimage-1.0 via /v1/chat/completions and fix image streaming

Author: lijirou12

app/api/v1/chat.py

@@ -78,6 +78,7 @@ class ChatCompletionRequest(BaseModel):
     "1024x1792",
     "1024x1024",
 }
+SUPERIMAGE_MODEL_ID = "grok-superimage-1.0"
 
 
 def _validate_media_input(value: str, field_name: str, param: str):
@@ -165,6 +166,17 @@ def _image_field(response_format: str) -> str:
         return "url"
     return "b64_json"
 
+
+def _superimage_server_image_config() -> ImageConfig:
+    """Load server-side image generation parameters for grok-superimage-1.0."""
+    n = int(get_config("superimage.n", 1) or 1)
+    size = str(get_config("superimage.size", "1024x1024") or "1024x1024")
+    response_format = str(
+        get_config("superimage.response_format", get_config("app.image_format") or "url")
+        or "url"
+    )
+    return ImageConfig(n=n, size=size, response_format=response_format)
+
 def _validate_image_config(image_conf: ImageConfig, *, stream: bool):
     n = image_conf.n or 1
     if n < 1 or n > 10:
@@ -514,7 +526,7 @@ def validate_request(request: ChatCompletionRequest):
                 param="messages",
                 code="empty_prompt",
             )
-        image_conf = request.image_config or ImageConfig()
+        image_conf = _superimage_server_image_config() if request.model == SUPERIMAGE_MODEL_ID else (request.image_config or ImageConfig())
         n = image_conf.n or 1
         if not (1 <= n <= 10):
             raise ValidationException(
@@ -685,7 +697,7 @@ async def chat_completions(request: ChatCompletionRequest):
         is_stream = (
             request.stream if request.stream is not None else get_config("app.stream")
         )
-        image_conf = request.image_config or ImageConfig()
+        image_conf = _superimage_server_image_config() if request.model == SUPERIMAGE_MODEL_ID else (request.image_config or ImageConfig())
         _validate_image_config(image_conf, stream=bool(is_stream))
         response_format = _resolve_image_format(image_conf.response_format)
         response_field = _image_field(response_format)

app/services/grok/services/image.py

@@ -436,6 +436,7 @@ def _sse(self, event: str, data: dict) -> str:
 
     async def process(self, response: AsyncIterable[dict]) -> AsyncGenerator[str, None]:
         images: Dict[str, Dict] = {}
+        emitted_chat_chunk = False
 
         async for item in response:
             if item.get("type") == "error":
@@ -515,6 +516,7 @@ async def process(self, response: AsyncIterable[dict]) -> AsyncGenerator[str, No
                     if not self._id_generated:
                         self._response_id = make_response_id()
                         self._id_generated = True
+                    emitted_chat_chunk = True
                     yield self._sse(
                         "chat.completion.chunk",
                         make_chat_chunk(
@@ -593,6 +595,7 @@ async def process(self, response: AsyncIterable[dict]) -> AsyncGenerator[str, No
 
             if self.chat_format:
                 # OpenAI ChatCompletion chunk format
+                emitted_chat_chunk = True
                 yield self._sse(
                     "chat.completion.chunk",
                     make_chat_chunk(
@@ -624,6 +627,23 @@ async def process(self, response: AsyncIterable[dict]) -> AsyncGenerator[str, No
                     },
                 )
 
+        if self.chat_format:
+            if not self._id_generated:
+                self._response_id = make_response_id()
+                self._id_generated = True
+            if not emitted_chat_chunk:
+                yield self._sse(
+                    "chat.completion.chunk",
+                    make_chat_chunk(
+                        self._response_id,
+                        self.model,
+                        "",
+                        index=0,
+                        is_final=True,
+                    ),
+                )
+            yield "data: [DONE]\n\n"
+
 
 class ImageWSCollectProcessor(ImageWSBaseProcessor):
     """WebSocket image non-stream processor."""

app/services/grok/services/image_edit.py

@@ -323,6 +323,7 @@ async def process(
     ) -> AsyncGenerator[str, None]:
         """Process stream response."""
         final_images = []
+        emitted_chat_chunk = False
         idle_timeout = get_config("image.stream_timeout")
 
         try:
@@ -352,6 +353,7 @@ async def process(
                         if not self._id_generated:
                             self._response_id = make_response_id()
                             self._id_generated = True
+                        emitted_chat_chunk = True
                         yield self._sse(
                             "chat.completion.chunk",
                             make_chat_chunk(
@@ -421,6 +423,7 @@ async def process(
 
                 if self.chat_format:
                     # OpenAI ChatCompletion chunk format
+                    emitted_chat_chunk = True
                     yield self._sse(
                         "chat.completion.chunk",
                         make_chat_chunk(
@@ -450,6 +453,23 @@ async def process(
                             },
                         },
                     )
+
+            if self.chat_format:
+                if not self._id_generated:
+                    self._response_id = make_response_id()
+                    self._id_generated = True
+                if not emitted_chat_chunk:
+                    yield self._sse(
+                        "chat.completion.chunk",
+                        make_chat_chunk(
+                            self._response_id,
+                            self.model,
+                            "",
+                            index=0,
+                            is_final=True,
+                        ),
+                    )
+                yield "data: [DONE]\n\n"
         except asyncio.CancelledError:
             logger.debug("Image stream cancelled by client")
         except StreamIdleTimeoutError as e:

app/services/grok/services/model.py

@@ -174,6 +174,18 @@ class ModelService:
             is_image_edit=False,
             is_video=False,
         ),
+        ModelInfo(
+            model_id="grok-superimage-1.0",
+            grok_model="grok-3",
+            model_mode="MODEL_MODE_FAST",
+            tier=Tier.BASIC,
+            cost=Cost.HIGH,
+            display_name="Grok SuperImage",
+            description="Imagine waterfall image generation model for chat completions",
+            is_image=True,
+            is_image_edit=False,
+            is_video=False,
+        ),
         ModelInfo(
             model_id="grok-imagine-1.0",
             grok_model="grok-3",

config.defaults.toml

@@ -110,6 +110,17 @@ medium_min_bytes = 30000
 # 判定为最终图的最小字节数
 final_min_bytes = 100000
 
+
+# ==================== SuperImage 配置 ====================
+[superimage]
+# 仅对 grok-superimage-1.0 生效，由服务端统一控制，不使用客户端 image_config
+n = 1
+# 图片尺寸：1280x720 / 720x1280 / 1792x1024 / 1024x1792 / 1024x1024
+size = "1024x1024"
+# 响应格式：url / b64_json / base64
+response_format = "url"
+
+
 # ==================== 视频配置 ====================
 [video]
 # Reverse 接口并发上限

readme.md

@@ -109,6 +109,7 @@ docker compose up -d
 | `grok-4.1-thinking` | 4 | Basic/Super | 支持 | 支持 | - |
 | `grok-4.20-beta` | 1 | Basic/Super | 支持 | 支持 | - |
 | `grok-imagine-1.0` | - | Basic/Super | - | 支持 | - |
+| `grok-superimage-1.0` | - | Basic/Super | - | 支持 | - |
 | `grok-imagine-1.0-edit` | - | Basic/Super | - | 支持 | - |
 | `grok-imagine-1.0-video` | - | Basic/Super | - | - | 支持 |
 
@@ -151,7 +152,7 @@ curl http://localhost:8000/v1/chat/completions \
 | └─`video_length` | integer | 视频时长 (秒) | `6`, `10`, `15` |
 | └─`resolution_name` | string | 分辨率 | `480p`, `720p` |
 | └─`preset` | string | 风格预设 | `fun`, `normal`, `spicy`, `custom` |
-| `image_config` | object | **图片模型专用配置对象** | 支持：`grok-imagine-1.0` / `grok-imagine-1.0-edit` |
+| `image_config` | object | **图片模型专用配置对象** | 支持：`grok-imagine-1.0` / `grok-superimage-1.0` / `grok-imagine-1.0-edit` |
 | └─`n` | integer | 生成数量 | `1` ~ `10` |
 | └─`size` | string | 图片尺寸 | `1280x720`, `720x1280`, `1792x1024`, `1024x1792`, `1024x1024` |
 | └─`response_format` | string | 响应格式 | `url`, `b64_json`, `base64` |
@@ -177,6 +178,7 @@ curl http://localhost:8000/v1/chat/completions \
 - `image_url/input_audio/file` 仅支持 URL 或 Data URI（`data:<mime>;base64,...`），裸 base64 会报错。
 - `reasoning_effort`：`none` 表示不输出思考，其他值都会输出思考内容。
 - 工具调用为**提示词模拟 + 客户端执行回填**：模型通过 `<tool_call>{...}</tool_call>` 输出调用请求，服务端解析为 `tool_calls`；不执行工具。
+- `grok-superimage-1.0` 与瀑布流 imagine 生成链路一致，可直接通过 `/v1/chat/completions` 调用；其 `n/size/response_format` 由服务端 `[superimage]` 统一控制。
 - `grok-imagine-1.0-edit` 必须提供图片，多图默认取**最后 3 张**与最后一个文本。
 - `grok-imagine-1.0-video` 支持文生视频与图生视频（通过 `image_url` 传参考图，**仅取第 1 张**）。
 - 除上述外的其他参数将自动丢弃并忽略。