Add async image task compatibility

Dockerfile

@@ -2,9 +2,10 @@ FROM alpine:3.22 AS source
 
 RUN apk add --no-cache git
 RUN git clone --depth 1 --branch v1.0.0-rc.22 https://github.com/QuantumNous/new-api.git /src
+COPY image_url_compat.go image_url_compat_test.go image_task_compat.go image_task_compat_test.go /src/relay/channel/openai/
 COPY codex-image-b64.patch /tmp/codex-image-b64.patch
-RUN git -C /src apply --check /tmp/codex-image-b64.patch \
-    && git -C /src apply /tmp/codex-image-b64.patch
+RUN git -C /src apply --unidiff-zero --check /tmp/codex-image-b64.patch \
+    && git -C /src apply --unidiff-zero /tmp/codex-image-b64.patch
 
 FROM oven/bun:1 AS web-builder
 
@@ -24,7 +25,7 @@ RUN go mod download
 COPY --from=source /src ./
 COPY --from=web-builder /build/web/dist ./web/dist
 RUN go test ./relay/channel/openai \
-    && go build -ldflags "-s -w -X 'github.com/QuantumNous/new-api/common.Version=v1.0.0-rc.22-codex-image-b64'" -o new-api
+    && go build -ldflags "-s -w -X 'github.com/QuantumNous/new-api/common.Version=v1.0.0-rc.22-codex-image-compat'" -o new-api
 
 FROM debian:bookworm-slim
 
@@ -37,7 +38,11 @@ RUN apt-get update \
 
 COPY --from=go-builder /build/new-api /new-api
 COPY --from=source /src/LICENSE /src/NOTICE /src/THIRD-PARTY-LICENSES.md /licenses/
-ENV PORT=7860 VERSION=v1.0.0-rc.22-codex-image-b64
+ENV PORT=7860 \
+    VERSION=v1.0.0-rc.22-codex-image-compat \
+    CODEX_IMAGE_URL_TO_B64=true \
+    CODEX_IMAGE_TASK_POLL=true \
+    CODEX_IMAGE_TASK_POLL_TIMEOUT_SECONDS=120
 EXPOSE 7860
 WORKDIR /data
 USER root

README.md

@@ -9,3 +9,9 @@ license: mit
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+This Space includes Codex image compatibility by default:
+
+- asynchronous `202 image.task` responses are polled for up to 120 seconds;
+- final image URLs are converted to `b64_json`;
+- transient image download errors and upstream 5xx responses are retried up to three times without resubmitting the generation task.

codex-image-b64.patch

@@ -1,282 +1,42 @@
-From a7a127e93518b4b91820d23b4b508a70f9834a98 Mon Sep 17 00:00:00 2001
-From: Claude Code <wechatbot@dev.local>
-Date: Wed, 29 Jul 2026 18:14:19 +0800
-Subject: [PATCH] Add optional image URL base64 compatibility
-
----
- .env.example                                  |   2 +
- relay/channel/openai/image_url_compat.go      | 162 ++++++++++++++++++
- relay/channel/openai/image_url_compat_test.go |  70 ++++++++
- relay/channel/openai/relay_image.go           |  10 ++
- 4 files changed, 244 insertions(+)
- create mode 100644 relay/channel/openai/image_url_compat.go
- create mode 100644 relay/channel/openai/image_url_compat_test.go
-
-diff --git a/.env.example b/.env.example
-index d62e114..76ea82f 100644
---- a/.env.example
-+++ b/.env.example
-@@ -1,5 +1,7 @@
- # 端口号
- # PORT=3000
-+# Convert URL-based OpenAI image responses to b64_json for strict clients such as Codex.
-+# CODEX_IMAGE_URL_TO_B64=false
- # 前端基础URL
- # FRONTEND_BASE_URL=https://your-frontend-url.com
- 
-diff --git a/relay/channel/openai/image_url_compat.go b/relay/channel/openai/image_url_compat.go
-new file mode 100644
-index 0000000..e0f222c
---- /dev/null
-+++ b/relay/channel/openai/image_url_compat.go
-@@ -0,0 +1,162 @@
-+package openai
-+
-+import (
-+	"encoding/base64"
-+	"encoding/json"
-+	"fmt"
-+	"io"
-+	"net/http"
-+	"strings"
-+	"time"
-+
-+	"github.com/QuantumNous/new-api/common"
-+)
-+
-+const maxImageURLCompatBytes int64 = 40 * 1024 * 1024
-+
-+type imageURLCompatDownloadFunc func(string, ...string) (*http.Response, error)
-+
-+type imageURLCompatStats struct {
-+	Converted       int
-+	DownloadedBytes int64
-+	DownloadTime    time.Duration
-+	EncodeTime      time.Duration
-+	TotalTime       time.Duration
-+}
-+
-+func (s imageURLCompatStats) ServerTiming() string {
-+	return fmt.Sprintf(
-+		"image-url-download;dur=%.3f, image-b64-encode;dur=%.3f, image-url-compat;dur=%.3f",
-+		float64(s.DownloadTime.Microseconds())/1000,
-+		float64(s.EncodeTime.Microseconds())/1000,
-+		float64(s.TotalTime.Microseconds())/1000,
-+	)
-+}
-+
-+func (s imageURLCompatStats) LogMessage() string {
-+	return fmt.Sprintf(
-+		"image URL compatibility converted=%d bytes=%d download_ms=%.3f encode_ms=%.3f total_ms=%.3f",
-+		s.Converted,
-+		s.DownloadedBytes,
-+		float64(s.DownloadTime.Microseconds())/1000,
-+		float64(s.EncodeTime.Microseconds())/1000,
-+		float64(s.TotalTime.Microseconds())/1000,
-+	)
-+}
-+
-+func convertOpenAIImageURLsToBase64(responseBody []byte, download imageURLCompatDownloadFunc) ([]byte, imageURLCompatStats, error) {
-+	var stats imageURLCompatStats
-+	if !common.GetEnvOrDefaultBool("CODEX_IMAGE_URL_TO_B64", false) {
-+		return responseBody, stats, nil
-+	}
-+
-+	startedAt := time.Now()
-+	var payload map[string]json.RawMessage
-+	if err := common.Unmarshal(responseBody, &payload); err != nil {
-+		return nil, stats, fmt.Errorf("decode image compatibility response: %w", err)
-+	}
-+	dataJSON, ok := payload["data"]
-+	if !ok {
-+		return responseBody, stats, nil
-+	}
-+
-+	var images []map[string]json.RawMessage
-+	if err := common.Unmarshal(dataJSON, &images); err != nil {
-+		return nil, stats, fmt.Errorf("decode image compatibility data: %w", err)
-+	}
-+
-+	for _, image := range images {
-+		if jsonString(image["b64_json"]) != "" {
-+			continue
-+		}
-+
-+		var imageURL string
-+		var sourceField string
-+		for _, field := range []string{"url", "result_url", "image_url"} {
-+			if value := jsonString(image[field]); value != "" {
-+				imageURL = value
-+				sourceField = field
-+				break
-+			}
-+		}
-+		if imageURL == "" {
-+			continue
-+		}
-+
-+		downloadStartedAt := time.Now()
-+		imageResponse, err := download(imageURL, "OpenAI image URL compatibility")
+diff --git a/relay/channel/openai/adaptor.go b/relay/channel/openai/adaptor.go
+index 4f1c4286..c05ef093 100644
+--- a/relay/channel/openai/adaptor.go
++++ b/relay/channel/openai/adaptor.go
+@@ -624,3 +624 @@ func (a *Adaptor) DoRequest(c *gin.Context, info *relaycommon.RelayInfo, request
+-	if info.RelayMode == relayconstant.RelayModeAudioTranscription ||
+-		info.RelayMode == relayconstant.RelayModeAudioTranslation ||
+-		(info.RelayMode == relayconstant.RelayModeImagesEdits && !isJSONRequest(c)) {
++	if info.RelayMode == relayconstant.RelayModeAudioTranscription || info.RelayMode == relayconstant.RelayModeAudioTranslation {
+@@ -628 +626,9 @@ func (a *Adaptor) DoRequest(c *gin.Context, info *relaycommon.RelayInfo, request
+-	} else if info.RelayMode == relayconstant.RelayModeRealtime {
++	}
++	if info.RelayMode == relayconstant.RelayModeImagesEdits && !isJSONRequest(c) {
++		response, err := channel.DoFormRequest(a, c, info, requestBody)
 +		if err != nil {
-+			return nil, stats, fmt.Errorf("download image compatibility URL: %w", err)
++			return nil, err
 +		}
-+		imageBytes, readErr := readImageURLCompatResponse(imageResponse)
-+		stats.DownloadTime += time.Since(downloadStartedAt)
-+		if readErr != nil {
-+			return nil, stats, readErr
-+		}
-+
-+		encodeStartedAt := time.Now()
-+		encodedJSON, err := common.Marshal(base64.StdEncoding.EncodeToString(imageBytes))
-+		if err != nil {
-+			return nil, stats, fmt.Errorf("encode image compatibility response: %w", err)
-+		}
-+		image["b64_json"] = encodedJSON
-+		delete(image, sourceField)
-+		stats.EncodeTime += time.Since(encodeStartedAt)
-+		stats.Converted++
-+		stats.DownloadedBytes += int64(len(imageBytes))
-+	}
-+
-+	if stats.Converted == 0 {
-+		return responseBody, stats, nil
++		return resolveOpenAIImageTask(c, info, response)
 +	}
++	if info.RelayMode == relayconstant.RelayModeRealtime {
+@@ -630,2 +635,0 @@ func (a *Adaptor) DoRequest(c *gin.Context, info *relaycommon.RelayInfo, request
+-	} else {
+-		return channel.DoApiRequest(a, c, info, requestBody)
+@@ -632,0 +637,9 @@ func (a *Adaptor) DoRequest(c *gin.Context, info *relaycommon.RelayInfo, request
 +
-+	encodeStartedAt := time.Now()
-+	dataJSON, err := common.Marshal(images)
++	response, err := channel.DoApiRequest(a, c, info, requestBody)
 +	if err != nil {
-+		return nil, stats, fmt.Errorf("encode image compatibility data: %w", err)
++		return nil, err
 +	}
-+	payload["data"] = dataJSON
-+	convertedBody, err := common.Marshal(payload)
-+	stats.EncodeTime += time.Since(encodeStartedAt)
-+	stats.TotalTime = time.Since(startedAt)
-+	if err != nil {
-+		return nil, stats, fmt.Errorf("encode image compatibility payload: %w", err)
-+	}
-+	return convertedBody, stats, nil
-+}
-+
-+func jsonString(raw json.RawMessage) string {
-+	if len(raw) == 0 {
-+		return ""
-+	}
-+	var value string
-+	if err := common.Unmarshal(raw, &value); err != nil {
-+		return ""
-+	}
-+	return strings.TrimSpace(value)
-+}
-+
-+func readImageURLCompatResponse(response *http.Response) ([]byte, error) {
-+	if response == nil || response.Body == nil {
-+		return nil, fmt.Errorf("image compatibility download returned an empty response")
-+	}
-+	defer response.Body.Close()
-+	if response.StatusCode < http.StatusOK || response.StatusCode >= http.StatusMultipleChoices {
-+		return nil, fmt.Errorf("image compatibility download returned HTTP %d", response.StatusCode)
-+	}
-+	if response.ContentLength > maxImageURLCompatBytes {
-+		return nil, fmt.Errorf("image compatibility download exceeds %d bytes", maxImageURLCompatBytes)
-+	}
-+
-+	imageBytes, err := io.ReadAll(io.LimitReader(response.Body, maxImageURLCompatBytes+1))
-+	if err != nil {
-+		return nil, fmt.Errorf("read image compatibility download: %w", err)
-+	}
-+	if int64(len(imageBytes)) > maxImageURLCompatBytes {
-+		return nil, fmt.Errorf("image compatibility download exceeds %d bytes", maxImageURLCompatBytes)
-+	}
-+	if len(imageBytes) == 0 {
-+		return nil, fmt.Errorf("image compatibility download returned an empty body")
++	if info.RelayMode == relayconstant.RelayModeImagesGenerations || info.RelayMode == relayconstant.RelayModeImagesEdits {
++		return resolveOpenAIImageTask(c, info, response)
 +	}
-+	return imageBytes, nil
-+}
-diff --git a/relay/channel/openai/image_url_compat_test.go b/relay/channel/openai/image_url_compat_test.go
-new file mode 100644
-index 0000000..2722bba
---- /dev/null
-+++ b/relay/channel/openai/image_url_compat_test.go
-@@ -0,0 +1,70 @@
-+package openai
-+
-+import (
-+	"bytes"
-+	"io"
-+	"net/http"
-+	"testing"
-+
-+	"github.com/QuantumNous/new-api/common"
-+	"github.com/stretchr/testify/assert"
-+	"github.com/stretchr/testify/require"
-+)
-+
-+func TestConvertOpenAIImageURLsToBase64Disabled(t *testing.T) {
-+	t.Setenv("CODEX_IMAGE_URL_TO_B64", "false")
-+	body := []byte(`{"created":1,"data":[{"url":"https://example.com/image.png"}]}`)
-+
-+	converted, stats, err := convertOpenAIImageURLsToBase64(body, func(string, ...string) (*http.Response, error) {
-+		t.Fatal("download must not run while compatibility is disabled")
-+		return nil, nil
-+	})
-+
-+	require.NoError(t, err)
-+	assert.Equal(t, body, converted)
-+	assert.Zero(t, stats.Converted)
-+}
-+
-+func TestConvertOpenAIImageURLsToBase64PreservesResponseFields(t *testing.T) {
-+	t.Setenv("CODEX_IMAGE_URL_TO_B64", "true")
-+	image := []byte("test-image")
-+	body := []byte(`{"created":1,"data":[{"url":"https://example.com/image.png","revised_prompt":"kept"}],"usage":{"total_tokens":7},"custom":{"kept":true}}`)
-+
-+	converted, stats, err := convertOpenAIImageURLsToBase64(body, func(rawURL string, reason ...string) (*http.Response, error) {
-+		assert.Equal(t, "https://example.com/image.png", rawURL)
-+		assert.Equal(t, []string{"OpenAI image URL compatibility"}, reason)
-+		return &http.Response{
-+			StatusCode:    http.StatusOK,
-+			ContentLength: int64(len(image)),
-+			Body:          io.NopCloser(bytes.NewReader(image)),
-+		}, nil
-+	})
-+
-+	require.NoError(t, err)
-+	assert.Equal(t, 1, stats.Converted)
-+	assert.Equal(t, int64(len(image)), stats.DownloadedBytes)
-+
-+	var payload map[string]any
-+	require.NoError(t, common.Unmarshal(converted, &payload))
-+	data := payload["data"].([]any)
-+	item := data[0].(map[string]any)
-+	assert.Equal(t, "dGVzdC1pbWFnZQ==", item["b64_json"])
-+	assert.Equal(t, "kept", item["revised_prompt"])
-+	assert.NotContains(t, item, "url")
-+	assert.Equal(t, float64(7), payload["usage"].(map[string]any)["total_tokens"])
-+	assert.Equal(t, true, payload["custom"].(map[string]any)["kept"])
-+	assert.Contains(t, stats.ServerTiming(), "image-url-compat")
-+}
-+
-+func TestReadImageURLCompatResponseRejectsOversize(t *testing.T) {
-+	response := &http.Response{
-+		StatusCode:    http.StatusOK,
-+		ContentLength: maxImageURLCompatBytes + 1,
-+		Body:          io.NopCloser(bytes.NewReader([]byte("unused"))),
-+	}
-+
-+	_, err := readImageURLCompatResponse(response)
-+
-+	require.Error(t, err)
-+	assert.Contains(t, err.Error(), "exceeds")
-+}
++	return response, nil
 diff --git a/relay/channel/openai/relay_image.go b/relay/channel/openai/relay_image.go
-index e0f09aa..a6cfad1 100644
+index 1e6be0dd..240e6eca 100644
 --- a/relay/channel/openai/relay_image.go
 +++ b/relay/channel/openai/relay_image.go
-@@ -39,6 +39,16 @@ func OpenaiImageHandler(c *gin.Context, info *relaycommon.RelayInfo, resp *http.
- 		return nil, types.NewOpenAIError(err, types.ErrorCodeReadResponseBodyFailed, http.StatusInternalServerError)
- 	}
- 
-+	responseBody, compatStats, err := convertOpenAIImageURLsToBase64(responseBody, service.DoDownloadRequest)
+@@ -41,0 +42,10 @@ func OpenaiImageHandler(c *gin.Context, info *relaycommon.RelayInfo, resp *http.
++	responseBody, compatStats, err := convertOpenAIImageURLsToBase64(responseBody, downloadOpenAIImageURLCompat)
 +	if err != nil {
 +		return nil, types.NewOpenAIError(err, types.ErrorCodeBadResponseBody, http.StatusBadGateway)
 +	}
@@ -286,6 +46,3 @@ index e0f09aa..a6cfad1 100644
 +		logger.LogInfo(c, compatStats.LogMessage())
 +	}
 +
- 	var usageResp dto.SimpleResponse
- 	err = common.Unmarshal(responseBody, &usageResp)
- 	if err != nil {

image_task_compat.go

@@ -0,0 +1,370 @@
+package openai
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/QuantumNous/new-api/common"
+	"github.com/QuantumNous/new-api/logger"
+	relaycommon "github.com/QuantumNous/new-api/relay/common"
+	"github.com/QuantumNous/new-api/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+const (
+	maxImageTaskResponseBytes    int64 = 64 * 1024 * 1024
+	defaultImageTaskPollTimeout        = 120 * time.Second
+	defaultImageTaskPollDelay          = 2 * time.Second
+	minImageTaskPollDelay              = 250 * time.Millisecond
+	maxImageTaskPollDelay              = 5 * time.Second
+	maxImageTaskPollErrors             = 3
+)
+
+type openAIImageTaskEnvelope struct {
+	Object      string `json:"object"`
+	Status      string `json:"status"`
+	TaskID      string `json:"task_id"`
+	ID          string `json:"id"`
+	PollURL     string `json:"poll_url"`
+	ResultURL   string `json:"result_url"`
+	PollAfterMS int64  `json:"poll_after_ms"`
+	Error       string `json:"error"`
+	ErrorCode   string `json:"error_code"`
+}
+
+type imageTaskPollStats struct {
+	TaskID   string
+	Attempts int
+	Duration time.Duration
+}
+
+type imageTaskWaitFunc func(context.Context, time.Duration) error
+
+func resolveOpenAIImageTask(c *gin.Context, info *relaycommon.RelayInfo, response *http.Response) (*http.Response, error) {
+	if !common.GetEnvOrDefaultBool("CODEX_IMAGE_TASK_POLL", false) || response == nil || response.StatusCode != http.StatusAccepted {
+		return response, nil
+	}
+	if info == nil {
+		return nil, fmt.Errorf("image task relay info is missing")
+	}
+
+	client, err := service.GetHttpClientWithProxy(info.ChannelSetting.Proxy)
+	if err != nil {
+		return nil, fmt.Errorf("create image task poll client: %w", err)
+	}
+
+	timeoutSeconds := common.GetEnvOrDefault("CODEX_IMAGE_TASK_POLL_TIMEOUT_SECONDS", int(defaultImageTaskPollTimeout/time.Second))
+	if timeoutSeconds < 1 {
+		timeoutSeconds = int(defaultImageTaskPollTimeout / time.Second)
+	}
+	if timeoutSeconds > 600 {
+		timeoutSeconds = 600
+	}
+
+	startedAt := time.Now()
+	resolved, stats, err := pollOpenAIImageTask(
+		c.Request.Context(),
+		response,
+		client,
+		time.Duration(timeoutSeconds)*time.Second,
+		waitForOpenAIImageTask,
+	)
+	stats.Duration = time.Since(startedAt)
+	if err != nil {
+		return nil, err
+	}
+	if stats.Attempts > 0 {
+		logger.LogInfo(c, fmt.Sprintf(
+			"image task compatibility completed task_id=%s attempts=%d total_ms=%.3f",
+			maskImageTaskID(stats.TaskID),
+			stats.Attempts,
+			float64(stats.Duration.Microseconds())/1000,
+		))
+		resolved.Header.Set("X-New-API-Image-Task-Compat", "polled")
+	}
+	return resolved, nil
+}
+
+func pollOpenAIImageTask(
+	ctx context.Context,
+	initial *http.Response,
+	client *http.Client,
+	timeout time.Duration,
+	wait imageTaskWaitFunc,
+) (*http.Response, imageTaskPollStats, error) {
+	var stats imageTaskPollStats
+	if initial == nil || initial.Body == nil {
+		return nil, stats, fmt.Errorf("image task response is empty")
+	}
+	if initial.StatusCode != http.StatusAccepted {
+		return initial, stats, nil
+	}
+
+	initialBody, err := readImageTaskResponseBody(initial)
+	if err != nil {
+		return nil, stats, err
+	}
+	initial.Body = io.NopCloser(bytes.NewReader(initialBody))
+	initial.ContentLength = int64(len(initialBody))
+
+	task, isTask, err := parseOpenAIImageTask(initialBody)
+	if err != nil {
+		return nil, stats, err
+	}
+	if !isTask {
+		return initial, stats, nil
+	}
+
+	stats.TaskID = firstNonEmpty(task.TaskID, task.ID)
+	baseURL, err := imageTaskBaseURL(initial)
+	if err != nil {
+		return nil, stats, err
+	}
+	pollClient := *client
+	pollClient.CheckRedirect = func(request *http.Request, via []*http.Request) error {
+		if len(via) >= 10 {
+			return fmt.Errorf("image task polling stopped after 10 redirects")
+		}
+		if request == nil || request.URL == nil ||
+			!strings.EqualFold(baseURL.Scheme, request.URL.Scheme) ||
+			!strings.EqualFold(baseURL.Host, request.URL.Host) {
+			return fmt.Errorf("image task redirect must use the original upstream origin")
+		}
+		return nil
+	}
+	client = &pollClient
+	pollURL, err := resolveImageTaskPollURL(baseURL, firstNonEmpty(task.PollURL, task.ResultURL))
+	if err != nil {
+		return nil, stats, err
+	}
+
+	deadline := time.Now().Add(timeout)
+	consecutiveErrors := 0
+	for {
+		if remaining := time.Until(deadline); remaining <= 0 {
+			return nil, stats, fmt.Errorf("image task polling timed out after %s (task_id=%s)", timeout, maskImageTaskID(stats.TaskID))
+		}
+
+		delay := imageTaskPollDelay(task.PollAfterMS)
+		if remaining := time.Until(deadline); delay > remaining {
+			delay = remaining
+		}
+		if err := wait(ctx, delay); err != nil {
+			return nil, stats, fmt.Errorf("image task polling stopped: %w", err)
+		}
+
+		request, err := http.NewRequestWithContext(ctx, http.MethodGet, pollURL.String(), nil)
+		if err != nil {
+			return nil, stats, fmt.Errorf("create image task poll request: %w", err)
+		}
+		copyImageTaskAuthHeaders(request.Header, initial.Request)
+		request.Header.Set("Accept", "application/json")
+
+		pollResponse, err := client.Do(request)
+		stats.Attempts++
+		if err != nil {
+			consecutiveErrors++
+			if consecutiveErrors >= maxImageTaskPollErrors {
+				return nil, stats, fmt.Errorf("poll image task after %d consecutive errors: %w", consecutiveErrors, err)
+			}
+			continue
+		}
+
+		pollBody, readErr := readImageTaskResponseBody(pollResponse)
+		if readErr != nil {
+			return nil, stats, readErr
+		}
+		if pollResponse.StatusCode >= http.StatusInternalServerError {
+			consecutiveErrors++
+			if consecutiveErrors >= maxImageTaskPollErrors {
+				return nil, stats, fmt.Errorf("poll image task returned HTTP %d after %d attempts", pollResponse.StatusCode, consecutiveErrors)
+			}
+			continue
+		}
+		consecutiveErrors = 0
+		if pollResponse.StatusCode < http.StatusOK || pollResponse.StatusCode >= http.StatusMultipleChoices {
+			return nil, stats, fmt.Errorf("poll image task returned HTTP %d", pollResponse.StatusCode)
+		}
+
+		if isFinalOpenAIImageResponse(pollBody) {
+			pollResponse.StatusCode = http.StatusOK
+			pollResponse.Status = fmt.Sprintf("%d %s", http.StatusOK, http.StatusText(http.StatusOK))
+			pollResponse.Body = io.NopCloser(bytes.NewReader(pollBody))
+			pollResponse.ContentLength = int64(len(pollBody))
+			pollResponse.Header.Del("Content-Encoding")
+			pollResponse.Header.Set("Content-Length", strconv.FormatInt(int64(len(pollBody)), 10))
+			return pollResponse, stats, nil
+		}
+
+		nextTask, nextIsTask, err := parseOpenAIImageTask(pollBody)
+		if err != nil {
+			return nil, stats, err
+		}
+		if !nextIsTask {
+			return nil, stats, fmt.Errorf("image task poll response is neither a task nor a final image response")
+		}
+		task = nextTask
+		if nextID := firstNonEmpty(task.TaskID, task.ID); nextID != "" {
+			stats.TaskID = nextID
+		}
+
+		switch strings.ToLower(strings.TrimSpace(task.Status)) {
+		case "failed", "cancelled", "canceled", "expired":
+			message := firstNonEmpty(task.Error, task.ErrorCode, task.Status)
+			return nil, stats, fmt.Errorf("image task %s: %s", maskImageTaskID(stats.TaskID), message)
+		case "completed", "succeeded", "success":
+			return nil, stats, fmt.Errorf("image task %s completed without image data", maskImageTaskID(stats.TaskID))
+		}
+
+		if nextRawURL := firstNonEmpty(task.PollURL, task.ResultURL); nextRawURL != "" {
+			pollURL, err = resolveImageTaskPollURL(baseURL, nextRawURL)
+			if err != nil {
+				return nil, stats, err
+			}
+		}
+	}
+}
+
+func parseOpenAIImageTask(body []byte) (openAIImageTaskEnvelope, bool, error) {
+	var task openAIImageTaskEnvelope
+	if err := common.Unmarshal(body, &task); err != nil {
+		return task, false, fmt.Errorf("decode image task response: %w", err)
+	}
+	if !strings.EqualFold(strings.TrimSpace(task.Object), "image.task") {
+		return task, false, nil
+	}
+	if firstNonEmpty(task.PollURL, task.ResultURL) == "" {
+		return task, false, fmt.Errorf("image task response is missing poll_url")
+	}
+	return task, true, nil
+}
+
+func isFinalOpenAIImageResponse(body []byte) bool {
+	var payload map[string]json.RawMessage
+	if err := common.Unmarshal(body, &payload); err != nil {
+		return false
+	}
+	if _, ok := payload["created"]; !ok {
+		return false
+	}
+	var images []json.RawMessage
+	if err := common.Unmarshal(payload["data"], &images); err != nil {
+		return false
+	}
+	return len(images) > 0
+}
+
+func imageTaskBaseURL(response *http.Response) (*url.URL, error) {
+	if response.Request == nil || response.Request.URL == nil {
+		return nil, fmt.Errorf("image task response is missing its upstream request URL")
+	}
+	base := response.Request.URL
+	if base.Scheme != "http" && base.Scheme != "https" {
+		return nil, fmt.Errorf("unsupported image task upstream scheme: %s", base.Scheme)
+	}
+	if base.User != nil || base.Hostname() == "" {
+		return nil, fmt.Errorf("invalid image task upstream URL")
+	}
+	return base, nil
+}
+
+func resolveImageTaskPollURL(baseURL *url.URL, rawURL string) (*url.URL, error) {
+	if baseURL == nil {
+		return nil, fmt.Errorf("image task upstream URL is missing")
+	}
+	reference, err := url.Parse(strings.TrimSpace(rawURL))
+	if err != nil {
+		return nil, fmt.Errorf("parse image task poll URL: %w", err)
+	}
+	resolved := baseURL.ResolveReference(reference)
+	if resolved.Scheme != "http" && resolved.Scheme != "https" {
+		return nil, fmt.Errorf("unsupported image task poll scheme: %s", resolved.Scheme)
+	}
+	if resolved.User != nil || resolved.Hostname() == "" {
+		return nil, fmt.Errorf("invalid image task poll URL")
+	}
+	if !strings.EqualFold(baseURL.Scheme, resolved.Scheme) || !strings.EqualFold(baseURL.Host, resolved.Host) {
+		return nil, fmt.Errorf("image task poll URL must use the original upstream origin")
+	}
+	return resolved, nil
+}
+
+func copyImageTaskAuthHeaders(destination http.Header, source *http.Request) {
+	if source == nil {
+		return
+	}
+	for _, name := range []string{"Authorization", "Api-Key", "X-Api-Key"} {
+		for _, value := range source.Header.Values(name) {
+			destination.Add(name, value)
+		}
+	}
+}
+
+func readImageTaskResponseBody(response *http.Response) ([]byte, error) {
+	if response == nil || response.Body == nil {
+		return nil, fmt.Errorf("image task response is empty")
+	}
+	defer response.Body.Close()
+	if response.ContentLength > maxImageTaskResponseBytes {
+		return nil, fmt.Errorf("image task response exceeds %d bytes", maxImageTaskResponseBytes)
+	}
+	body, err := io.ReadAll(io.LimitReader(response.Body, maxImageTaskResponseBytes+1))
+	if err != nil {
+		return nil, fmt.Errorf("read image task response: %w", err)
+	}
+	if int64(len(body)) > maxImageTaskResponseBytes {
+		return nil, fmt.Errorf("image task response exceeds %d bytes", maxImageTaskResponseBytes)
+	}
+	return body, nil
+}
+
+func imageTaskPollDelay(milliseconds int64) time.Duration {
+	if milliseconds <= 0 {
+		return defaultImageTaskPollDelay
+	}
+	delay := time.Duration(milliseconds) * time.Millisecond
+	if delay < minImageTaskPollDelay {
+		return minImageTaskPollDelay
+	}
+	if delay > maxImageTaskPollDelay {
+		return maxImageTaskPollDelay
+	}
+	return delay
+}
+
+func waitForOpenAIImageTask(ctx context.Context, delay time.Duration) error {
+	timer := time.NewTimer(delay)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, value := range values {
+		if trimmed := strings.TrimSpace(value); trimmed != "" {
+			return trimmed
+		}
+	}
+	return ""
+}
+
+func maskImageTaskID(taskID string) string {
+	taskID = strings.TrimSpace(taskID)
+	if len(taskID) <= 12 {
+		return taskID
+	}
+	return taskID[:8] + "..." + taskID[len(taskID)-4:]
+}

image_task_compat_test.go

@@ -0,0 +1,120 @@
+package openai
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/QuantumNous/new-api/common"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestPollOpenAIImageTaskReturnsFinalResponse(t *testing.T) {
+	attempts := 0
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		assert.Equal(t, "Bearer test-key", request.Header.Get("Authorization"))
+		attempts++
+		writer.Header().Set("Content-Type", "application/json")
+		if attempts == 1 {
+			writer.WriteHeader(http.StatusAccepted)
+			_, _ = writer.Write([]byte(`{"object":"image.task","status":"processing","task_id":"task-1","poll_url":"/v1/images/tasks/task-1","poll_after_ms":1}`))
+			return
+		}
+		_, _ = writer.Write([]byte(`{"created":123,"data":[{"url":"https://example.com/image.png"}],"usage":{"total_tokens":7}}`))
+	}))
+	defer server.Close()
+
+	request := httptest.NewRequest(http.MethodPost, server.URL+"/v1/images/edits", nil)
+	request.Header.Set("Authorization", "Bearer test-key")
+	initial := &http.Response{
+		StatusCode: http.StatusAccepted,
+		Header:     make(http.Header),
+		Request:    request,
+		Body: io.NopCloser(bytes.NewBufferString(
+			`{"object":"image.task","status":"queued","task_id":"task-1","poll_url":"/v1/images/tasks/task-1","poll_after_ms":1}`,
+		)),
+	}
+
+	resolved, stats, err := pollOpenAIImageTask(context.Background(), initial, server.Client(), time.Second, noImageTaskWait)
+
+	require.NoError(t, err)
+	require.NotNil(t, resolved)
+	assert.Equal(t, http.StatusOK, resolved.StatusCode)
+	assert.Equal(t, 2, stats.Attempts)
+	assert.Equal(t, "task-1", stats.TaskID)
+	resolvedBody, err := io.ReadAll(resolved.Body)
+	require.NoError(t, err)
+	assert.True(t, isFinalOpenAIImageResponse(resolvedBody))
+
+	var payload map[string]any
+	require.NoError(t, common.Unmarshal(resolvedBody, &payload))
+	assert.Equal(t, float64(123), payload["created"])
+}
+
+func TestPollOpenAIImageTaskRejectsCrossOriginPollURL(t *testing.T) {
+	request := httptest.NewRequest(http.MethodPost, "https://upstream.example/v1/images/edits", nil)
+	initial := &http.Response{
+		StatusCode: http.StatusAccepted,
+		Header:     make(http.Header),
+		Request:    request,
+		Body: io.NopCloser(bytes.NewBufferString(
+			`{"object":"image.task","status":"queued","task_id":"task-1","poll_url":"https://other.example/tasks/task-1"}`,
+		)),
+	}
+
+	_, _, err := pollOpenAIImageTask(context.Background(), initial, http.DefaultClient, time.Second, noImageTaskWait)
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "original upstream origin")
+}
+
+func TestPollOpenAIImageTaskReturnsFailure(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		writer.Header().Set("Content-Type", "application/json")
+		_, _ = writer.Write([]byte(`{"object":"image.task","status":"failed","task_id":"task-1","poll_url":"/v1/images/tasks/task-1","error":"generation failed"}`))
+	}))
+	defer server.Close()
+
+	request := httptest.NewRequest(http.MethodPost, server.URL+"/v1/images/edits", nil)
+	initial := &http.Response{
+		StatusCode: http.StatusAccepted,
+		Header:     make(http.Header),
+		Request:    request,
+		Body: io.NopCloser(bytes.NewBufferString(
+			`{"object":"image.task","status":"queued","task_id":"task-1","poll_url":"/v1/images/tasks/task-1"}`,
+		)),
+	}
+
+	_, _, err := pollOpenAIImageTask(context.Background(), initial, server.Client(), time.Second, noImageTaskWait)
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "generation failed")
+}
+
+func TestPollOpenAIImageTaskStopsWhenContextIsCancelled(t *testing.T) {
+	request := httptest.NewRequest(http.MethodPost, "https://upstream.example/v1/images/edits", nil)
+	initial := &http.Response{
+		StatusCode: http.StatusAccepted,
+		Header:     make(http.Header),
+		Request:    request,
+		Body: io.NopCloser(bytes.NewBufferString(
+			`{"object":"image.task","status":"queued","task_id":"task-1","poll_url":"/v1/images/tasks/task-1"}`,
+		)),
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, _, err := pollOpenAIImageTask(ctx, initial, http.DefaultClient, time.Second, waitForOpenAIImageTask)
+
+	require.Error(t, err)
+	assert.ErrorIs(t, err, context.Canceled)
+}
+
+func noImageTaskWait(context.Context, time.Duration) error {
+	return nil
+}

image_url_compat.go

@@ -0,0 +1,284 @@
+package openai
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/QuantumNous/new-api/common"
+	"github.com/QuantumNous/new-api/service"
+	"github.com/QuantumNous/new-api/setting/system_setting"
+)
+
+const maxImageURLCompatBytes int64 = 40 * 1024 * 1024
+
+const maxImageURLCompatDownloadAttempts = 3
+
+type imageURLCompatDownloadFunc func(string, ...string) (*http.Response, error)
+
+type imageURLCompatStats struct {
+	Converted       int
+	DownloadedBytes int64
+	DownloadTime    time.Duration
+	EncodeTime      time.Duration
+	TotalTime       time.Duration
+}
+
+func downloadOpenAIImageURLCompat(rawURL string, reason ...string) (*http.Response, error) {
+	parsedURL, err := url.Parse(rawURL)
+	if err != nil {
+		return nil, fmt.Errorf("parse image compatibility URL: %w", err)
+	}
+
+	proxyURL, err := http.ProxyFromEnvironment(&http.Request{URL: parsedURL})
+	if err != nil {
+		return nil, fmt.Errorf("resolve image compatibility proxy: %w", err)
+	}
+	if proxyURL == nil {
+		return service.DoDownloadRequest(rawURL, reason...)
+	}
+	if err := validateImageURLCompatProxyTarget(parsedURL); err != nil {
+		return nil, fmt.Errorf("request reject: %w", err)
+	}
+
+	baseClient := service.GetHttpClient()
+	client := &http.Client{
+		Transport: baseClient.Transport,
+		Timeout:   baseClient.Timeout,
+		Jar:       baseClient.Jar,
+		CheckRedirect: func(request *http.Request, via []*http.Request) error {
+			if len(via) >= 10 {
+				return fmt.Errorf("stopped after 10 redirects")
+			}
+			redirectProxy, err := http.ProxyFromEnvironment(request)
+			if err != nil {
+				return fmt.Errorf("resolve redirect proxy: %w", err)
+			}
+			if redirectProxy == nil {
+				return fmt.Errorf("image compatibility redirect left the configured proxy")
+			}
+			return validateImageURLCompatProxyTarget(request.URL)
+		},
+	}
+
+	common.SysLog(fmt.Sprintf(
+		"downloading image compatibility URL through configured proxy: %s, reason: %s",
+		common.MaskSensitiveInfo(rawURL),
+		strings.Join(reason, ", "),
+	))
+	return retryImageURLCompatDownload(
+		func() (*http.Response, error) { return client.Get(rawURL) },
+		time.Sleep,
+	)
+}
+
+func retryImageURLCompatDownload(request func() (*http.Response, error), wait func(time.Duration)) (*http.Response, error) {
+	var lastErr error
+	for attempt := 1; attempt <= maxImageURLCompatDownloadAttempts; attempt++ {
+		response, err := request()
+		if err == nil && response != nil && response.StatusCode < http.StatusInternalServerError {
+			return response, nil
+		}
+		if response != nil && response.Body != nil {
+			response.Body.Close()
+		}
+		if err != nil {
+			lastErr = err
+		} else if response == nil {
+			lastErr = fmt.Errorf("image compatibility download returned an empty response")
+		} else {
+			lastErr = fmt.Errorf("image compatibility download returned HTTP %d", response.StatusCode)
+		}
+		if attempt < maxImageURLCompatDownloadAttempts {
+			wait(time.Duration(attempt) * 300 * time.Millisecond)
+		}
+	}
+	return nil, lastErr
+}
+
+// Clash Fake-IP addresses are local DNS placeholders. When an HTTP proxy is
+// selected, validate the hostname and port without resolving that placeholder.
+func validateImageURLCompatProxyTarget(parsedURL *url.URL) error {
+	if parsedURL == nil || parsedURL.Hostname() == "" {
+		return fmt.Errorf("invalid image compatibility URL")
+	}
+	if parsedURL.Scheme != "http" && parsedURL.Scheme != "https" {
+		return fmt.Errorf("unsupported image compatibility URL scheme: %s", parsedURL.Scheme)
+	}
+	if parsedURL.User != nil {
+		return fmt.Errorf("image compatibility URL must not contain credentials")
+	}
+
+	port := 80
+	if parsedURL.Scheme == "https" {
+		port = 443
+	}
+	if parsedURL.Port() != "" {
+		parsedPort, err := strconv.Atoi(parsedURL.Port())
+		if err != nil {
+			return fmt.Errorf("invalid image compatibility port: %w", err)
+		}
+		port = parsedPort
+	}
+
+	fetchSetting := system_setting.GetFetchSetting()
+	if fetchSetting == nil || !fetchSetting.EnableSSRFProtection {
+		return nil
+	}
+	protection, err := common.NewSSRFProtectionFromFetchSetting(
+		fetchSetting.AllowPrivateIp,
+		fetchSetting.DomainFilterMode,
+		fetchSetting.IpFilterMode,
+		fetchSetting.DomainList,
+		fetchSetting.IpList,
+		fetchSetting.AllowedPorts,
+		fetchSetting.ApplyIPFilterForDomain,
+	)
+	if err != nil {
+		return err
+	}
+	return protection.ValidateNetworkTarget(parsedURL.Hostname(), port)
+}
+
+func (s imageURLCompatStats) ServerTiming() string {
+	return fmt.Sprintf(
+		"image-url-download;dur=%.3f, image-b64-encode;dur=%.3f, image-url-compat;dur=%.3f",
+		float64(s.DownloadTime.Microseconds())/1000,
+		float64(s.EncodeTime.Microseconds())/1000,
+		float64(s.TotalTime.Microseconds())/1000,
+	)
+}
+
+func (s imageURLCompatStats) LogMessage() string {
+	return fmt.Sprintf(
+		"image URL compatibility converted=%d bytes=%d download_ms=%.3f encode_ms=%.3f total_ms=%.3f",
+		s.Converted,
+		s.DownloadedBytes,
+		float64(s.DownloadTime.Microseconds())/1000,
+		float64(s.EncodeTime.Microseconds())/1000,
+		float64(s.TotalTime.Microseconds())/1000,
+	)
+}
+
+func convertOpenAIImageURLsToBase64(responseBody []byte, download imageURLCompatDownloadFunc) ([]byte, imageURLCompatStats, error) {
+	var stats imageURLCompatStats
+	if !common.GetEnvOrDefaultBool("CODEX_IMAGE_URL_TO_B64", false) {
+		return responseBody, stats, nil
+	}
+
+	startedAt := time.Now()
+	var payload map[string]json.RawMessage
+	if err := common.Unmarshal(responseBody, &payload); err != nil {
+		return nil, stats, fmt.Errorf("decode image compatibility response: %w", err)
+	}
+	dataJSON, ok := payload["data"]
+	if !ok {
+		return responseBody, stats, nil
+	}
+
+	var images []map[string]json.RawMessage
+	if err := common.Unmarshal(dataJSON, &images); err != nil {
+		return nil, stats, fmt.Errorf("decode image compatibility data: %w", err)
+	}
+
+	for _, image := range images {
+		if jsonString(image["b64_json"]) != "" {
+			continue
+		}
+
+		var imageURL string
+		var sourceField string
+		for _, field := range []string{"url", "result_url", "image_url"} {
+			if value := jsonString(image[field]); value != "" {
+				imageURL = value
+				sourceField = field
+				break
+			}
+		}
+		if imageURL == "" {
+			continue
+		}
+
+		downloadStartedAt := time.Now()
+		imageResponse, err := download(imageURL, "OpenAI image URL compatibility")
+		if err != nil {
+			return nil, stats, fmt.Errorf("download image compatibility URL: %w", err)
+		}
+		imageBytes, readErr := readImageURLCompatResponse(imageResponse)
+		stats.DownloadTime += time.Since(downloadStartedAt)
+		if readErr != nil {
+			return nil, stats, readErr
+		}
+
+		encodeStartedAt := time.Now()
+		encodedJSON, err := common.Marshal(base64.StdEncoding.EncodeToString(imageBytes))
+		if err != nil {
+			return nil, stats, fmt.Errorf("encode image compatibility response: %w", err)
+		}
+		image["b64_json"] = encodedJSON
+		delete(image, sourceField)
+		stats.EncodeTime += time.Since(encodeStartedAt)
+		stats.Converted++
+		stats.DownloadedBytes += int64(len(imageBytes))
+	}
+
+	if stats.Converted == 0 {
+		return responseBody, stats, nil
+	}
+
+	encodeStartedAt := time.Now()
+	dataJSON, err := common.Marshal(images)
+	if err != nil {
+		return nil, stats, fmt.Errorf("encode image compatibility data: %w", err)
+	}
+	payload["data"] = dataJSON
+	convertedBody, err := common.Marshal(payload)
+	stats.EncodeTime += time.Since(encodeStartedAt)
+	stats.TotalTime = time.Since(startedAt)
+	if err != nil {
+		return nil, stats, fmt.Errorf("encode image compatibility payload: %w", err)
+	}
+	return convertedBody, stats, nil
+}
+
+func jsonString(raw json.RawMessage) string {
+	if len(raw) == 0 {
+		return ""
+	}
+	var value string
+	if err := common.Unmarshal(raw, &value); err != nil {
+		return ""
+	}
+	return strings.TrimSpace(value)
+}
+
+func readImageURLCompatResponse(response *http.Response) ([]byte, error) {
+	if response == nil || response.Body == nil {
+		return nil, fmt.Errorf("image compatibility download returned an empty response")
+	}
+	defer response.Body.Close()
+	if response.StatusCode < http.StatusOK || response.StatusCode >= http.StatusMultipleChoices {
+		return nil, fmt.Errorf("image compatibility download returned HTTP %d", response.StatusCode)
+	}
+	if response.ContentLength > maxImageURLCompatBytes {
+		return nil, fmt.Errorf("image compatibility download exceeds %d bytes", maxImageURLCompatBytes)
+	}
+
+	imageBytes, err := io.ReadAll(io.LimitReader(response.Body, maxImageURLCompatBytes+1))
+	if err != nil {
+		return nil, fmt.Errorf("read image compatibility download: %w", err)
+	}
+	if int64(len(imageBytes)) > maxImageURLCompatBytes {
+		return nil, fmt.Errorf("image compatibility download exceeds %d bytes", maxImageURLCompatBytes)
+	}
+	if len(imageBytes) == 0 {
+		return nil, fmt.Errorf("image compatibility download returned an empty body")
+	}
+	return imageBytes, nil
+}

image_url_compat_test.go

@@ -0,0 +1,129 @@
+package openai
+
+import (
+	"bytes"
+	"errors"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/QuantumNous/new-api/common"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestConvertOpenAIImageURLsToBase64Disabled(t *testing.T) {
+	t.Setenv("CODEX_IMAGE_URL_TO_B64", "false")
+	body := []byte(`{"created":1,"data":[{"url":"https://example.com/image.png"}]}`)
+
+	converted, stats, err := convertOpenAIImageURLsToBase64(body, func(string, ...string) (*http.Response, error) {
+		t.Fatal("download must not run while compatibility is disabled")
+		return nil, nil
+	})
+
+	require.NoError(t, err)
+	assert.Equal(t, body, converted)
+	assert.Zero(t, stats.Converted)
+}
+
+func TestConvertOpenAIImageURLsToBase64PreservesResponseFields(t *testing.T) {
+	t.Setenv("CODEX_IMAGE_URL_TO_B64", "true")
+	image := []byte("test-image")
+	body := []byte(`{"created":1,"data":[{"url":"https://example.com/image.png","revised_prompt":"kept"}],"usage":{"total_tokens":7},"custom":{"kept":true}}`)
+
+	converted, stats, err := convertOpenAIImageURLsToBase64(body, func(rawURL string, reason ...string) (*http.Response, error) {
+		assert.Equal(t, "https://example.com/image.png", rawURL)
+		assert.Equal(t, []string{"OpenAI image URL compatibility"}, reason)
+		return &http.Response{
+			StatusCode:    http.StatusOK,
+			ContentLength: int64(len(image)),
+			Body:          io.NopCloser(bytes.NewReader(image)),
+		}, nil
+	})
+
+	require.NoError(t, err)
+	assert.Equal(t, 1, stats.Converted)
+	assert.Equal(t, int64(len(image)), stats.DownloadedBytes)
+
+	var payload map[string]any
+	require.NoError(t, common.Unmarshal(converted, &payload))
+	data := payload["data"].([]any)
+	item := data[0].(map[string]any)
+	assert.Equal(t, "dGVzdC1pbWFnZQ==", item["b64_json"])
+	assert.Equal(t, "kept", item["revised_prompt"])
+	assert.NotContains(t, item, "url")
+	assert.Equal(t, float64(7), payload["usage"].(map[string]any)["total_tokens"])
+	assert.Equal(t, true, payload["custom"].(map[string]any)["kept"])
+	assert.Contains(t, stats.ServerTiming(), "image-url-compat")
+}
+
+func TestReadImageURLCompatResponseRejectsOversize(t *testing.T) {
+	response := &http.Response{
+		StatusCode:    http.StatusOK,
+		ContentLength: maxImageURLCompatBytes + 1,
+		Body:          io.NopCloser(bytes.NewReader([]byte("unused"))),
+	}
+
+	_, err := readImageURLCompatResponse(response)
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "exceeds")
+}
+
+func TestDownloadOpenAIImageURLCompatRejectsPrivateLiteral(t *testing.T) {
+	_, err := downloadOpenAIImageURLCompat("https://127.0.0.1/image.png")
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "private IP address not allowed")
+}
+
+func TestRetryImageURLCompatDownloadRecoversFromTransientError(t *testing.T) {
+	attempts := 0
+	waits := 0
+
+	response, err := retryImageURLCompatDownload(func() (*http.Response, error) {
+		attempts++
+		if attempts == 1 {
+			return nil, errors.New("EOF")
+		}
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Body:       io.NopCloser(bytes.NewBufferString("image")),
+		}, nil
+	}, func(time.Duration) {
+		waits++
+	})
+
+	require.NoError(t, err)
+	require.NotNil(t, response)
+	assert.Equal(t, 2, attempts)
+	assert.Equal(t, 1, waits)
+}
+
+func TestRetryImageURLCompatDownloadStopsAfterLimit(t *testing.T) {
+	attempts := 0
+
+	response, err := retryImageURLCompatDownload(func() (*http.Response, error) {
+		attempts++
+		return nil, errors.New("EOF")
+	}, func(time.Duration) {})
+
+	require.Error(t, err)
+	assert.Nil(t, response)
+	assert.Equal(t, maxImageURLCompatDownloadAttempts, attempts)
+}
+
+func TestRetryImageURLCompatDownloadRejectsEmptyResponse(t *testing.T) {
+	attempts := 0
+
+	response, err := retryImageURLCompatDownload(func() (*http.Response, error) {
+		attempts++
+		return nil, nil
+	}, func(time.Duration) {})
+
+	require.Error(t, err)
+	assert.Nil(t, response)
+	assert.Contains(t, err.Error(), "empty response")
+	assert.Equal(t, maxImageURLCompatDownloadAttempts, attempts)
+}