refactor(api): extract URL utils and apply HF image proxy

- Extract getOrigin and toProxyUrl from openai/routes.ts to utils/url.ts
- Apply HuggingFace image proxy in /api/generate and /api/generate-hf
- Add unit tests for toProxyUrl
- Update biome schema to 2.3.11

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: WuMingDao

apps/api/src/app.ts

@@ -48,7 +48,7 @@ import {
 import { registerOpenAIRoutes } from './openai/routes'
 import { getProvider, hasProvider } from './providers'
 import { createVideoTask, getVideoTaskStatus } from './providers/gitee'
-import { callGradioApi, formatDimensions, formatDuration } from './utils'
+import { callGradioApi, formatDimensions, formatDuration, getOrigin, toProxyUrl } from './utils'
 
 export interface AppConfig {
   corsOrigins?: string[]
@@ -507,7 +507,7 @@ function createApiApp(config: AppConfig = {}) {
       const providerName = providerConfig?.name || providerId
 
       const imageDetails: ImageDetails = {
-        url: result.url,
+        url: providerId === 'huggingface' ? toProxyUrl(getOrigin(c), result.url) : result.url,
         provider: providerName,
         model: modelName,
         dimensions: formatDimensions(width, height),
@@ -580,7 +580,7 @@ function createApiApp(config: AppConfig = {}) {
       const modelName = modelConfig?.name || modelId
 
       const imageDetails: ImageDetails = {
-        url: result.url,
+        url: toProxyUrl(getOrigin(c), result.url),
         provider: 'HuggingFace',
         model: modelName,
         dimensions: formatDimensions(width, height),

apps/api/src/openai/routes.ts

@@ -1,38 +1,12 @@
 import { Errors, getModelsByProvider, PROVIDER_CONFIGS } from '@z-image/shared'
-import type { Context, Hono } from 'hono'
+import type { Hono } from 'hono'
 import { sendError } from '../middleware'
 import { getProvider } from '../providers'
+import { getOrigin, toProxyUrl } from '../utils'
 import { convertRequest, convertResponse, parseBearerToken } from './adapter'
 import { resolveModel } from './model-resolver'
 import type { OpenAIImageRequest, OpenAIModelsListResponse } from './types'
 
-function getOrigin(c: Context): string {
-  try {
-    return new URL(c.req.url).origin
-  } catch {
-    return ''
-  }
-}
-
-function toProxyUrl(origin: string, url: string): string {
-  if (!origin) return url
-
-  try {
-    const parsed = new URL(url)
-    if (parsed.hostname.endsWith('.hf.space') && parsed.pathname.startsWith('/gradio_api/file=')) {
-      return `${origin}/api/proxy-image?url=${encodeURIComponent(url)}`
-    }
-  } catch {
-    // ignore invalid URL, fall back to raw string checks
-  }
-
-  if (url.includes('.hf.space/gradio_api/file=')) {
-    return `${origin}/api/proxy-image?url=${encodeURIComponent(url)}`
-  }
-
-  return url
-}
-
 function listModels(): OpenAIModelsListResponse {
   const created = 1700000000
   const giteeModels = getModelsByProvider('gitee').map((m) => m.id)

apps/api/src/utils/__tests__/url.test.ts

@@ -0,0 +1,38 @@
+/**
+ * Utils Unit Tests
+ * Tests for URL utilities
+ */
+
+import { describe, expect, it } from 'vitest'
+import { toProxyUrl } from '../url'
+
+describe('toProxyUrl', () => {
+  it('should return original url when origin is empty', () => {
+    expect(toProxyUrl('', 'https://example.com/image.png')).toBe('https://example.com/image.png')
+  })
+
+  it('should proxy HuggingFace gradio file URLs', () => {
+    const origin = 'https://example.com'
+    const url = 'https://abc123.hf.space/gradio_api/file=image.png'
+    expect(toProxyUrl(origin, url)).toBe(
+      'https://example.com/api/proxy-image?url=https%3A%2F%2Fabc123.hf.space%2Fgradio_api%2Ffile%3Dimage.png'
+    )
+  })
+
+  it('should proxy via string fallback for non-URL inputs', () => {
+    const origin = 'https://example.com'
+    const url = 'abc123.hf.space/gradio_api/file=image.png'
+    expect(toProxyUrl(origin, url)).toBe(
+      'https://example.com/api/proxy-image?url=abc123.hf.space%2Fgradio_api%2Ffile%3Dimage.png'
+    )
+  })
+
+  it('should not proxy unrelated URLs', () => {
+    expect(toProxyUrl('https://example.com', 'https://abc123.hf.space/file=image.png')).toBe(
+      'https://abc123.hf.space/file=image.png'
+    )
+    expect(toProxyUrl('https://example.com', 'https://example.com/image.png')).toBe(
+      'https://example.com/image.png'
+    )
+  })
+})

apps/api/src/utils/index.ts

@@ -4,3 +4,4 @@
 
 export * from './format'
 export * from './gradio'
+export * from './url'

apps/api/src/utils/url.ts

@@ -0,0 +1,28 @@
+import type { Context } from 'hono'
+
+export function getOrigin(c: Context): string {
+  try {
+    return new URL(c.req.url).origin
+  } catch {
+    return ''
+  }
+}
+
+export function toProxyUrl(origin: string, url: string): string {
+  if (!origin) return url
+
+  try {
+    const parsed = new URL(url)
+    if (parsed.hostname.endsWith('.hf.space') && parsed.pathname.startsWith('/gradio_api/file=')) {
+      return `${origin}/api/proxy-image?url=${encodeURIComponent(url)}`
+    }
+  } catch {
+    // ignore invalid URL, fall back to raw string checks
+  }
+
+  if (url.includes('.hf.space/gradio_api/file=')) {
+    return `${origin}/api/proxy-image?url=${encodeURIComponent(url)}`
+  }
+
+  return url
+}

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.3.11/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",