HKUDS/DeepTutor · error · GenerationProviderError

Image generation request error: {exc}

Error message

Image generation request error: {exc}

What it means

A httpx.HTTPError occurred while POSTing {base}/images/generations or while downloading an image URL from the response (_materialize's GET runs inside the same try). The adapter wraps it in GenerationProviderError with the underlying exception chained.

Source

Thrown at deeptutor/services/imagegen/adapters/openai_compat.py:65

        if config.quality:
            payload["quality"] = config.quality
        if config.style:
            payload["style"] = config.style
        if config.response_format:
            payload["response_format"] = config.response_format

        logger.debug(
            "imagegen url=%s model=%s n=%d size=%s", url, config.model, max(1, n), config.size
        )
        try:
            async with httpx.AsyncClient(timeout=config.request_timeout) as client:
                resp = await client.post(url, headers=headers, json=payload)
                raise_for_provider(resp, "Image generation")
                images = [
                    await self._materialize(client, item) for item in self._extract_items(resp)
                ]
        except httpx.HTTPError as exc:
            raise GenerationProviderError(f"Image generation request error: {exc}") from exc
        if not images:
            raise GenerationProviderError("Image provider returned no images.")
        return images

    @staticmethod
    def _extract_items(resp: httpx.Response) -> list[dict[str, Any]]:
        data = resp.json()
        if isinstance(data, dict):
            items = data.get("data")
            if isinstance(items, list) and items:
                return [item for item in items if isinstance(item, dict)]
        raise GenerationProviderError("Image response had no `data` array.")

    async def _materialize(
        self, client: httpx.AsyncClient, item: dict[str, Any]
    ) -> tuple[bytes, str]:
        b64 = item.get("b64_json")
        if isinstance(b64, str) and b64:

View on GitHub (pinned to 3e82f13042)

Solutions

1. Confirm the API host is reachable (curl POST {base}/images/generations with the key)
2. Retry with exponential backoff for transient network errors
3. Configure proxy/trust env or fix TLS if that's the failure mode
4. Raise the httpx timeout — image generation routinely exceeds default client timeouts

for attempt in range(3):
    try:
        return await adapter.generate(prompt, config)
    except GenerationProviderError as exc:
        if "request error" not in str(exc) or attempt == 2:
            raise
        await asyncio.sleep(2 ** attempt)

When it happens

Trigger: Unreachable/black-holed API host, connection reset, timeout during generation, TLS failure, or the b64-less url item pointing at an unreachable file host.

Common situations: Firewalled or proxied egress, expired DNS, provider outage, self-signed cert on a gateway, timeout too short for image generation workloads.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• Image generation request error: {exc}
• TTS request error: {exc}
• STT request error: {exc}
• {self.name}: publish request failed: {exc}
• TTS request error: {detail}

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/3ad7705d18a9239e. Report an issue: GitHub.