HF fallback

Author: WuMingDao

apps/api/src/providers/huggingface.ts

@@ -2,7 +2,7 @@
  * HuggingFace Provider Implementation
  */
 
-import { Errors, HF_SPACES } from '@z-image/shared'
+import { ApiError, ApiErrorCode, Errors, HF_SPACES } from '@z-image/shared'
 import { MAX_INT32 } from '../constants'
 import { callGradioApi } from '../utils'
 import type { ImageProvider, ProviderGenerateRequest, ProviderGenerateResult } from './types'
@@ -28,6 +28,26 @@ function parseSeedFromResponse(modelId: string, result: unknown[], fallbackSeed:
   return fallbackSeed
 }
 
+function getCandidateBaseUrls(modelId: string): string[] {
+  const primary = HF_SPACES[modelId as keyof typeof HF_SPACES] || HF_SPACES['z-image-turbo']
+  // Known mirror space for z-image-turbo. Helps when a space is cold/blocked/deleted.
+  const fallbacks =
+    modelId === 'z-image-turbo' ? ['https://luca115-z-image-turbo.hf.space'] : ([] as string[])
+  return [primary, ...fallbacks].filter(Boolean)
+}
+
+function isNotFoundProviderError(err: unknown): boolean {
+  if (err instanceof ApiError) {
+    return err.code === ApiErrorCode.PROVIDER_ERROR && (err.details?.upstream || '').includes('404')
+  }
+  if (err && typeof err === 'object' && 'code' in err) {
+    const code = (err as { code?: unknown }).code
+    const details = (err as { details?: unknown }).details as { upstream?: string } | undefined
+    return code === ApiErrorCode.PROVIDER_ERROR && (details?.upstream || '').includes('404')
+  }
+  return false
+}
+
 /** Model-specific Gradio configurations */
 const MODEL_CONFIGS: Record<
   string,
@@ -58,31 +78,50 @@ export class HuggingFaceProvider implements ImageProvider {
   async generate(request: ProviderGenerateRequest): Promise<ProviderGenerateResult> {
     const seed = request.seed ?? Math.floor(Math.random() * MAX_INT32)
     const modelId = request.model || 'z-image-turbo'
-    const baseUrl = HF_SPACES[modelId as keyof typeof HF_SPACES] || HF_SPACES['z-image-turbo']
     const config = MODEL_CONFIGS[modelId] || MODEL_CONFIGS['z-image-turbo']
 
     // Debug: log model info (uncomment for debugging)
     // console.log(`[HuggingFace] Model: ${modelId}, BaseURL: ${baseUrl}`)
 
-    const data = await callGradioApi(
-      baseUrl,
-      config.endpoint,
-      config.buildData(request, seed),
-      request.authToken
-    )
+    let lastErr: unknown
+    let imageUrl: string | undefined
+    let data: unknown[] | undefined
+
+    for (const baseUrl of getCandidateBaseUrls(modelId)) {
+      try {
+        data = await callGradioApi(
+          baseUrl,
+          config.endpoint,
+          config.buildData(request, seed),
+          request.authToken
+        )
+
+        const result = data as Array<{ url?: string } | number | string>
+        const first = result[0]
+        const rawUrl =
+          typeof first === 'string' ? first : (first as { url?: string } | null | undefined)?.url
+        imageUrl = rawUrl ? normalizeImageUrl(baseUrl, rawUrl) : undefined
+        if (!imageUrl) {
+          // A successful call without an image payload is not a base-URL issue.
+          throw Errors.generationFailed('HuggingFace', 'No image returned')
+        }
+        break
+      } catch (err) {
+        lastErr = err
+        // Try next base URL only for 404-type provider errors.
+        if (isNotFoundProviderError(err)) continue
+        throw err
+      }
+    }
 
-    const result = data as Array<{ url?: string } | number | string>
-    const first = result[0]
-    const rawUrl =
-      typeof first === 'string' ? first : (first as { url?: string } | null | undefined)?.url
-    const imageUrl = rawUrl ? normalizeImageUrl(baseUrl, rawUrl) : undefined
     if (!imageUrl) {
+      if (lastErr) throw lastErr
       throw Errors.generationFailed('HuggingFace', 'No image returned')
     }
 
     return {
       url: imageUrl,
-      seed: parseSeedFromResponse(modelId, result, seed),
+      seed: parseSeedFromResponse(modelId, data as unknown[], seed),
     }
   }
 }

apps/api/src/utils/gradio.ts

@@ -106,8 +106,9 @@ export async function callGradioApi(
   // HuggingFace Spaces can be "cold" (starting/loading) and sometimes return transient 404/503.
   // Retry a few times to reduce false-negative failures in serverless runtimes (e.g. Cloudflare).
   let queueData: { event_id?: string } | null = null
+  const queueUrl = `${baseUrl}/gradio_api/call/${endpoint}`
   for (let attempt = 0; attempt < MAX_GRADIO_RETRIES; attempt++) {
-    const queue = await fetch(`${baseUrl}/gradio_api/call/${endpoint}`, {
+    const queue = await fetch(queueUrl, {
       method: 'POST',
       headers,
       body: JSON.stringify({ data }),
@@ -125,20 +126,21 @@ export async function callGradioApi(
       await sleep(600 * (attempt + 1))
       continue
     }
-    throw parseHuggingFaceError(errText || `Queue request failed: ${status}`, status)
+    throw parseHuggingFaceError(`${status} ${queueUrl}${errText ? `: ${errText}` : ''}`, status)
   }
 
   if (!queueData) {
-    throw Errors.providerError(PROVIDER_NAME, 'Queue request failed after retries')
+    throw Errors.providerError(PROVIDER_NAME, `Queue request failed after retries: ${queueUrl}`)
   }
 
   if (!queueData.event_id) {
     throw Errors.providerError(PROVIDER_NAME, 'No event_id returned from queue')
   }
 
   let text = ''
+  const resultUrl = `${baseUrl}/gradio_api/call/${endpoint}/${queueData.event_id}`
   for (let attempt = 0; attempt < MAX_GRADIO_RETRIES; attempt++) {
-    const result = await fetch(`${baseUrl}/gradio_api/call/${endpoint}/${queueData.event_id}`, {
+    const result = await fetch(resultUrl, {
       headers,
     })
 
@@ -154,7 +156,7 @@ export async function callGradioApi(
       await sleep(600 * (attempt + 1))
       continue
     }
-    throw parseHuggingFaceError(errText || `Result request failed: ${status}`, status)
+    throw parseHuggingFaceError(`${status} ${resultUrl}${errText ? `: ${errText}` : ''}`, status)
   }
 
   if (!text) {