How farishijazi/openai2civitai works
Project Type and Purpose
• This is a lightweight backend proxy server written in Python.
• It exposes an HTTP endpoint compatible with the OpenAI DALL-E image generation API (/v1/images/generations and /health).
• It’s meant to sit between an existing OpenAI-based client and the CivitAI service, requiring no client-side code changes other than pointing at this proxy.
High-Level Architecture & Components
a. External Clients
• Any OpenAI-compatible client (e.g., applications, cURL, Open-WebUI)
b. HTTP API Layer (server.py, app.py)
• /v1/images/generations – main proxy endpoint
• /health – health check
c. Configuration Layer (config.py, environment variables)
• Reads CIVITAI_API_TOKEN, CIVITAI_DEFAULT_MODEL, host/port, poll settings
d. Request Transformation
• prompt_parser.py – extracts and normalizes OpenAI-style JSON
• prompt_reviser.py – applies any additional parameter tweaks (e.g., size, flux mode)
e. CivitAI Client SDK (openai2civitai/civitai_py/civitai_py)
• Models (data classes) under models/
• Service clients under services/ (e.g., Jobs_service.py, async variants)
• HTTP client and API config (api_config.py)
f. Job Polling & Response Aggregation
• Polls CivitAI until images are ready (MAX_POLL_ATTEMPTS, POLL_INTERVAL)
• Collects URLs or blobs, wraps them in OpenAI’s response schema
g. Tests & Examples
• test_proxy.py – end-to-end proxy test
• openai2civitai/civitai_py/tests/ – unit tests for the SDK
• Example Streamlit demo under examples/streamlit_demo
h. Deployment
• Dockerfile, docker-compose.yml for containerized deployment
• GitHub Actions workflow for Docker publishing
Interactions & Data Flow
1. Client ➔ Proxy HTTP server
• Sends POST to /v1/images/generations with OpenAI JSON
2. Proxy
• Reads config.py for tokens and defaults
• prompt_parser and prompt_reviser convert request to CivitAI format
• Calls CivitAI SDK (Jobs_service.create_image, etc.)
3. CivitAI API
• Processes the job
• Proxy polls using the SDK’s async services until completion
4. Proxy
• Receives image URLs/blobs
• Wraps result in OpenAI image generation response format
5. Proxy ➔ Client
• Returns JSON mimicking the OpenAI response
Architectural Patterns & Design Principles
• Single-process HTTP “adapter” pattern (facade over CivitAI).
• Separation of concerns:
• API layer (FastAPI/Starlette or Flask alternative in server.py)
• Config layer (config.py)
• Transformation layer (prompt_parser.py, prompt_reviser.py)
• SDK layer (auto-generated CivitAI client under civitai_py)
• Polling mechanism as a resilience pattern for asynchronous CivitAI jobs.
• Containerization for easy deployment and portability.
Essential Elements
• Clear labels: e.g., “OpenAI Client,” “Proxy Server: /v1/images/generations,” “CivitAI SDK,” “CivitAI API.”
• Incoming HTTP request
• Outgoing SDK calls
• Polling loop
• Final HTTP response
• Blue for API boundaries
• Green for transformation/business logic
• Orange for third-party/external services