feat(api): add OpenAI-compatible /v1 images API

Adds /v1/images/generations + /v1/models and proxies HuggingFace Gradio URLs via /api/proxy-image.

Author: WuMingDao

apps/api/src/app.ts

@@ -45,6 +45,7 @@ import {
   sendError,
   timeout,
 } from './middleware'
+import { registerOpenAIRoutes } from './openai/routes'
 import { getProvider, hasProvider } from './providers'
 import { createVideoTask, getVideoTaskStatus } from './providers/gitee'
 import { callGradioApi, formatDimensions, formatDuration } from './utils'
@@ -53,26 +54,31 @@ export interface AppConfig {
   corsOrigins?: string[]
 }
 
-export function createApp(config: AppConfig = {}) {
-  const app = new Hono().basePath('/api')
-
-  // Default CORS origins for development
-  const defaultOrigins = ['http://localhost:5173', 'http://localhost:5174', 'http://localhost:3000']
-  const origins = config.corsOrigins || defaultOrigins
-
-  // Pre-create CORS middleware instance (optimization)
-  const corsMiddleware = cors({
+function createCorsMiddleware(origins: string[]) {
+  return cors({
     origin: origins,
     allowMethods: ['GET', 'POST', 'OPTIONS'],
     allowHeaders: [
       'Content-Type',
+      'Authorization',
       'X-API-Key',
       'X-HF-Token',
       'X-MS-Token',
       'X-DeepSeek-Token',
       'X-Request-ID',
     ],
   })
+}
+
+function createApiApp(config: AppConfig = {}) {
+  const app = new Hono().basePath('/api')
+
+  // Default CORS origins for development
+  const defaultOrigins = ['http://localhost:5173', 'http://localhost:5174', 'http://localhost:3000']
+  const origins = config.corsOrigins || defaultOrigins
+
+  // Pre-create CORS middleware instance (optimization)
+  const corsMiddleware = createCorsMiddleware(origins)
 
   // Global error handlers
   app.onError(errorHandler)
@@ -767,6 +773,39 @@ export function createApp(config: AppConfig = {}) {
   return app
 }
 
+function createOpenAIApp(config: AppConfig = {}) {
+  const app = new Hono().basePath('/v1')
+
+  const defaultOrigins = ['http://localhost:5173', 'http://localhost:5174', 'http://localhost:3000']
+  const origins = config.corsOrigins || defaultOrigins
+  const corsMiddleware = createCorsMiddleware(origins)
+
+  app.onError(errorHandler)
+  app.notFound(notFoundHandler)
+
+  app.use('/*', requestId)
+  app.use('/*', corsMiddleware)
+  app.use('/*', securityHeaders)
+  app.use('/*', requestLogger)
+
+  app.use('/*', timeout(120000))
+  app.use('/*', bodyLimit(50 * 1024))
+  app.use('/*', rateLimitPresets.generate)
+
+  registerOpenAIRoutes(app)
+
+  return app
+}
+
+export function createApp(config: AppConfig = {}) {
+  const app = new Hono()
+  app.onError(errorHandler)
+  app.notFound(notFoundHandler)
+  app.route('/', createOpenAIApp(config))
+  app.route('/', createApiApp(config))
+  return app
+}
+
 // Default app instance for simple usage
 const app = createApp()
 

apps/api/src/openai/__tests__/routes.test.ts

@@ -0,0 +1,146 @@
+/**
+ * OpenAI-Compatible Routes Tests (/v1)
+ * Tests with mocked fetch - no real API calls
+ */
+
+import { ApiErrorCode } from '@z-image/shared'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createApp } from '../../app'
+
+describe('OpenAI-compatible routes', () => {
+  const app = createApp()
+
+  beforeEach(() => {
+    vi.stubGlobal('fetch', vi.fn())
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('POST /v1/images/generations defaults to HuggingFace z-image-turbo', async () => {
+    const mockFetch = vi.mocked(fetch)
+
+    // Gradio queue
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ event_id: 'evt-1' }),
+    } as Response)
+
+    // Gradio result (SSE)
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      text: async () => 'event: complete\ndata: [{"url":"https://hf.space/img.png"}, 42]\n\n',
+    } as Response)
+
+    const res = await app.request('/v1/images/generations', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ prompt: 'a cat', size: '1024x1024' }),
+    })
+
+    expect(res.status).toBe(200)
+    const json = (await res.json()) as { created: number; data: Array<{ url: string }> }
+    expect(json.created).toBeTypeOf('number')
+    expect(json.data[0]?.url).toBe('https://hf.space/img.png')
+
+    expect(mockFetch.mock.calls[0]?.[0]).toContain('mrfakename-z-image-turbo.hf.space')
+  })
+
+  it('POST /v1/images/generations supports gitee/ model prefix + gitee: token', async () => {
+    const mockFetch = vi.mocked(fetch)
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ data: [{ url: 'https://example.com/gitee.png' }] }),
+    } as Response)
+
+    const res = await app.request('/v1/images/generations', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: 'Bearer gitee:test-api-key',
+      },
+      body: JSON.stringify({
+        model: 'gitee/z-image-turbo',
+        prompt: 'a bird',
+        size: '1024x768',
+        negative_prompt: 'blurry',
+      }),
+    })
+
+    expect(res.status).toBe(200)
+    const json = (await res.json()) as { data: Array<{ url: string }> }
+    expect(json.data[0]?.url).toBe('https://example.com/gitee.png')
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://ai.gitee.com/v1/images/generations',
+      expect.objectContaining({
+        method: 'POST',
+        headers: expect.objectContaining({
+          Authorization: 'Bearer test-api-key',
+        }),
+      })
+    )
+
+    const body = JSON.parse((mockFetch.mock.calls[0]?.[1]?.body as string) || '{}')
+    expect(body.width).toBe(1024)
+    expect(body.height).toBe(768)
+    expect(body.negative_prompt).toBe('blurry')
+  })
+
+  it('POST /v1/images/generations supports ms/ model prefix + ms: token', async () => {
+    const mockFetch = vi.mocked(fetch)
+
+    // submit
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ task_id: 'task-123' }),
+    } as Response)
+
+    // poll
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ task_status: 'SUCCEED', output_images: ['https://example.com/ms.png'] }),
+    } as Response)
+
+    const res = await app.request('/v1/images/generations', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: 'Bearer ms:token-12345678',
+      },
+      body: JSON.stringify({
+        model: 'ms/flux-2',
+        prompt: 'a robot',
+      }),
+    })
+
+    expect(res.status).toBe(200)
+    const json = (await res.json()) as { data: Array<{ url: string }> }
+    expect(json.data[0]?.url).toBe('https://example.com/ms.png')
+  })
+
+  it('POST /v1/images/generations rejects n != 1', async () => {
+    const res = await app.request('/v1/images/generations', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ prompt: 'a cat', n: 2 }),
+    })
+
+    expect(res.status).toBe(400)
+    const json = (await res.json()) as { code: string }
+    expect(json.code).toBe(ApiErrorCode.INVALID_PARAMS)
+  })
+
+  it('GET /v1/models returns OpenAI-like list', async () => {
+    const res = await app.request('/v1/models')
+    expect(res.status).toBe(200)
+
+    const json = (await res.json()) as { object: string; data: Array<{ id: string }> }
+    expect(json.object).toBe('list')
+    expect(json.data.map((m) => m.id)).toContain('z-image-turbo')
+    expect(json.data.map((m) => m.id)).toContain('gitee/z-image-turbo')
+    expect(json.data.map((m) => m.id)).toContain('ms/flux-2')
+  })
+})
+

apps/api/src/openai/adapter.ts

@@ -0,0 +1,75 @@
+import { Errors, type ProviderType, validateDimensions, validatePrompt, validateSteps } from '@z-image/shared'
+import type { ProviderGenerateRequest, ProviderGenerateResult } from '../providers/types'
+import type { OpenAIImageRequest, OpenAIImageResponse } from './types'
+
+export type OpenAIConvertedRequest = Pick<
+  ProviderGenerateRequest,
+  'prompt' | 'negativePrompt' | 'width' | 'height' | 'steps' | 'seed' | 'guidanceScale'
+>
+
+export function parseSize(size?: string): { width: number; height: number } {
+  if (!size) return { width: 1024, height: 1024 }
+
+  const [w, h] = size.split('x').map((n) => Number.parseInt(n, 10))
+  return {
+    width: Number.isFinite(w) && w > 0 ? w : 1024,
+    height: Number.isFinite(h) && h > 0 ? h : 1024,
+  }
+}
+
+export function parseBearerToken(authHeader?: string): { providerHint?: ProviderType; token?: string } {
+  if (!authHeader) return {}
+  if (!authHeader.startsWith('Bearer ')) return {}
+
+  const raw = authHeader.slice('Bearer '.length).trim()
+  if (!raw) return {}
+
+  if (raw.startsWith('gitee:')) {
+    const token = raw.slice('gitee:'.length).trim()
+    return token ? { providerHint: 'gitee', token } : {}
+  }
+  if (raw.startsWith('ms:')) {
+    const token = raw.slice('ms:'.length).trim()
+    return token ? { providerHint: 'modelscope', token } : {}
+  }
+
+  return { token: raw }
+}
+
+export function convertRequest(req: OpenAIImageRequest): OpenAIConvertedRequest {
+  const promptValidation = validatePrompt(req.prompt)
+  if (!promptValidation.valid) {
+    throw Errors.invalidPrompt(promptValidation.error || 'Invalid prompt')
+  }
+
+  const { width, height } = parseSize(req.size)
+  const dimensionsValidation = validateDimensions(width, height)
+  if (!dimensionsValidation.valid) {
+    throw Errors.invalidDimensions(dimensionsValidation.error || 'Invalid dimensions')
+  }
+
+  const steps = req.steps ?? (req.quality === 'hd' ? 30 : undefined)
+  if (steps !== undefined) {
+    const stepsValidation = validateSteps(steps)
+    if (!stepsValidation.valid) {
+      throw Errors.invalidParams('steps', stepsValidation.error || 'Invalid steps')
+    }
+  }
+
+  return {
+    prompt: req.prompt,
+    negativePrompt: req.negative_prompt,
+    width,
+    height,
+    steps,
+    seed: req.seed,
+    guidanceScale: req.guidance_scale,
+  }
+}
+
+export function convertResponse(result: ProviderGenerateResult): OpenAIImageResponse {
+  return {
+    created: Math.floor(Date.now() / 1000),
+    data: [{ url: result.url }],
+  }
+}

apps/api/src/openai/model-resolver.ts

@@ -0,0 +1,39 @@
+import type { ProviderType } from '@z-image/shared'
+
+interface ResolvedModel {
+  provider: ProviderType
+  model: string
+}
+
+const DEFAULT_HF_MODEL = 'z-image-turbo'
+const HF_MODELS = new Set(['z-image-turbo', 'qwen-image-fast', 'ovis-image', 'flux-1-schnell'])
+
+const GITEE_MODEL_ALIASES: Record<string, string> = {
+  'z-image-turbo': 'z-image-turbo',
+  'qwen-image': 'Qwen-Image',
+  'flux-1-krea-dev': 'FLUX_1-Krea-dev',
+  'flux-1-dev': 'FLUX.1-dev',
+}
+
+const MODELSCOPE_MODEL_ALIASES: Record<string, string> = {
+  'z-image-turbo': 'Tongyi-MAI/Z-Image-Turbo',
+  'flux-2': 'black-forest-labs/FLUX.2-dev',
+  'flux-1-krea-dev': 'black-forest-labs/FLUX.1-Krea-dev',
+  'flux-1': 'MusePublic/489_ckpt_FLUX_1',
+}
+
+export function resolveModel(modelParam?: string): ResolvedModel {
+  const model = (modelParam || DEFAULT_HF_MODEL).trim()
+
+  if (model.startsWith('gitee/')) {
+    const raw = model.slice('gitee/'.length)
+    return { provider: 'gitee', model: GITEE_MODEL_ALIASES[raw] || raw }
+  }
+
+  if (model.startsWith('ms/')) {
+    const raw = model.slice('ms/'.length)
+    return { provider: 'modelscope', model: MODELSCOPE_MODEL_ALIASES[raw] || raw }
+  }
+
+  return { provider: 'huggingface', model: HF_MODELS.has(model) ? model : DEFAULT_HF_MODEL }
+}