ImagineStudio

A native macOS app for generating images and videos using xAI's Grok and fal.ai APIs.

Features

• Text to Image — Generate images from text prompts with configurable aspect ratio, resolution, and batch count
• Image Editing — Upload a source image and describe edits via prompt
• Text to Video — Generate videos from text prompts with configurable duration and resolution
• Image to Video — Animate a still image into a video clip
• Multi-Provider — Switch between xAI (Grok) and fal.ai from Settings
• Media Library — Gallery view of all generations with search, filter by type, sort by date
• Favorites — Star any generation for quick access
• Albums — Create custom albums to organize your work
• Prompt History — Searchable history of all prompts, click to reuse
• Auto-save — All generated media saves to ~/Pictures/GrokImagine/ organized by date
• Secure API Keys — Stored in macOS Keychain, not plaintext

Supported Models

xAI

Type	Model	Notes
Image	Aurora (grok-2-image)	Default image model
Image	Grok Imagine (grok-imagine-image)	Alternative
Video	Grok Imagine Video (grok-imagine-video)	Up to 15 seconds

fal.ai

Type	Model	Notes
Image	FLUX 1.1 Pro Ultra (fal-ai/flux-pro/v1.1-ultra)	High quality, supports image-guided generation
Image	FLUX Dev (fal-ai/flux/dev)	Fast, good for iteration
Video	Wan 2.6 (wan/v2.6)	Up to 1080p, 5/10/15 second durations

Requirements

• macOS 13.0 (Ventura) or later
• Xcode 15.0 or later
• An API key from at least one provider:
  • xAI — https://console.x.ai
  • fal.ai — https://fal.ai/dashboard/keys

Setup

1. Open ImagineStudio.xcodeproj in Xcode
2. Select your development team under Signing & Capabilities
3. Build and run (Cmd+R)
4. Go to the Settings tab
5. Paste your API key(s) and click "Validate & Save"
6. Select your preferred provider and models
7. Start generating

Sandbox Entitlements

The app needs these entitlements (already configured in the project):

• Outgoing Connections (Client) — for API calls
• User Selected File — Read/Write — for the save location picker
• Pictures Folder — Read/Write — for saving to ~/Pictures/GrokImagine/

Architecture

SwiftUI + MVVM with dependency injection via AppState.

ImagineStudio/
├── ImagineStudioApp.swift          — App entry point
├── AppState.swift                  — Central state + dependency injection
├── Models/
│   ├── APIModels.swift             — API request/response types (xAI + fal.ai)
│   ├── GenerationModels.swift      — Data models + enums
│   └── AppSettings.swift           — Settings model with Codable migration
├── Services/
│   ├── APIService.swift            — xAI API client
│   ├── FalAPIService.swift         — fal.ai API client (sync + queue-based)
│   ├── KeychainService.swift       — Secure API key storage
│   ├── StorageService.swift        — File system operations
│   ├── DatabaseService.swift       — JSON metadata persistence
│   ├── ImageService.swift          — Image generation (routes by provider)
│   └── VideoService.swift          — Video generation + async polling
├── ViewModels/
│   ├── GenerateViewModel.swift     — Generation controls + state
│   ├── LibraryViewModel.swift      — Gallery with search/filter
│   ├── FavoritesViewModel.swift    — Starred items
│   └── SettingsViewModel.swift     — Settings + provider management
└── Views/
    ├── MainView.swift              — NavigationSplitView shell
    ├── SidebarView.swift           — Tab navigation + active polls
    ├── GenerateView.swift          — Prompt + params + output
    ├── LibraryView.swift           — Gallery grid
    ├── FavoritesView.swift         — Favorites grid
    ├── SettingsView.swift          — API keys + defaults
    ├── PromptHistoryView.swift     — Prompt history sheet
    ├── MediaPreviewCard.swift      — Thumbnail card
    └── Components/
        ├── OutputGridView.swift    — Reusable grid component
        └── VideoStatusBadge.swift  — Video polling status indicator

How It Works

Image generation sends a synchronous request to the selected provider's API and downloads the resulting image URLs to local storage.

Video generation is asynchronous. For xAI, the app polls GET /v1/videos/{request_id} every 5 seconds. For fal.ai, it submits to the queue API and polls the returned status_url until completion. Both have a 10-minute timeout. Pending polls resume automatically on app launch.

Storage — all media saves to ~/Pictures/GrokImagine/ in date-based subfolders. A metadata.json file tracks generations, favorites, albums, and prompt history.

Troubleshooting

• "No API key configured" — Go to Settings and add your key for the selected provider
• "HTTP 401/403" — API key is invalid or expired
• "HTTP 429" — Rate limited, wait a moment and retry
• "content_policy_violation" — fal.ai's content filter rejected the prompt
• Video stuck on "Generating..." — Videos can take several minutes. Check the sidebar for polling status.

License

This project is for personal use. API usage is subject to each provider's terms of service.