ALwrity/docs/image studio/IMAGE_STUDIO_QUICK_INTEGRATION_GUIDE.md

Image Studio: Quick Integration Guide

🎉 Phase 1, Module 1 (Create Studio) - BACKEND COMPLETE!

Status: Backend fully implemented and ready for use
What's Done: ✅ Backend services, ✅ API endpoints, ✅ WaveSpeed provider, ✅ Templates
What's Next: Frontend component integration

---

🚀 Quick Start (3 Steps)

Step 1: Add Environment Variable

Add to your .env file:

WAVESPEED_API_KEY=your_wavespeed_api_key_here

Step 2: Register Router

Add to backend/app.py:

from routers import image_studio

app.include_router(image_studio.router)

Step 3: Test the API

# Health check
curl http://localhost:8000/api/image-studio/health

# Get templates
curl http://localhost:8000/api/image-studio/templates \
  -H "Authorization: Bearer YOUR_TOKEN"

# Generate image
curl -X POST http://localhost:8000/api/image-studio/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Modern coffee shop interior",
    "template_id": "instagram_feed_square",
    "quality": "premium"
  }'

That's it! The backend is ready to use.

---

📦 What's Available Now

✅ Image Generation

• 5 AI Providers: Stability AI (Ultra/Core/SD3), WaveSpeed (Ideogram V3, Qwen), HuggingFace, Gemini
• 27 Platform Templates: Instagram, Facebook, Twitter, LinkedIn, YouTube, Pinterest, TikTok, Blog, Email, Website
• Smart Features: Auto-provider selection, prompt enhancement, batch generation (1-10 variations)

✅ API Endpoints

• POST /api/image-studio/create - Generate images
• GET /api/image-studio/templates - Get templates
• GET /api/image-studio/templates/search - Search templates
• GET /api/image-studio/templates/recommend - Get recommendations
• GET /api/image-studio/providers - Get provider info
• POST /api/image-studio/estimate-cost - Estimate costs
• GET /api/image-studio/platform-specs/{platform} - Get platform specs
• GET /api/image-studio/health - Health check

✅ Templates by Platform

Instagram (4 templates):

• instagram_feed_square - 1080x1080 (1:1)
• instagram_feed_portrait - 1080x1350 (4:5)
• instagram_story - 1080x1920 (9:16)
• instagram_reel_cover - 1080x1920 (9:16)

Facebook (4 templates):

• facebook_feed - 1200x630 (1.91:1)
• facebook_feed_square - 1080x1080 (1:1)
• facebook_story - 1080x1920 (9:16)
• facebook_cover - 820x312 (16:9)

Twitter/X (3 templates):

• twitter_post - 1200x675 (16:9)
• twitter_card - 1200x600 (2:1)
• twitter_header - 1500x500 (3:1)

LinkedIn (4 templates):

• linkedin_post - 1200x628 (1.91:1)
• linkedin_post_square - 1080x1080 (1:1)
• linkedin_article - 1200x627 (2:1)
• linkedin_cover - 1128x191 (4:1)

...and 12 more templates for YouTube, Pinterest, TikTok, Blog, Email, and Website!

---

💻 API Usage Examples

Example 1: Simple Generation with Template

Request:

POST /api/image-studio/create
{
  "prompt": "Modern minimalist workspace with laptop",
  "template_id": "linkedin_post",
  "quality": "premium"
}

Response:

{
  "success": true,
  "request": {
    "prompt": "Modern minimalist workspace with laptop",
    "enhanced_prompt": "Modern minimalist workspace with laptop, professional photography, high quality, detailed, sharp focus, natural lighting",
    "template_id": "linkedin_post",
    "template_name": "LinkedIn Post",
    "provider": "wavespeed",
    "model": "ideogram-v3-turbo",
    "dimensions": "1200x628",
    "quality": "premium"
  },
  "results": [
    {
      "image_base64": "iVBORw0KGgoAAAANS...",
      "width": 1200,
      "height": 628,
      "provider": "wavespeed",
      "model": "ideogram-v3-turbo",
      "variation": 1
    }
  ],
  "total_generated": 1
}

Example 2: Multiple Variations

Request:

POST /api/image-studio/create
{
  "prompt": "Product photography of smartphone",
  "width": 1080,
  "height": 1080,
  "provider": "wavespeed",
  "model": "ideogram-v3-turbo",
  "num_variations": 4,
  "quality": "premium"
}

Result: Generates 4 different variations of the same prompt.

Example 3: Get Templates for Instagram

Request:

GET /api/image-studio/templates?platform=instagram

Response:

{
  "templates": [
    {
      "id": "instagram_feed_square",
      "name": "Instagram Feed Post (Square)",
      "category": "social_media",
      "platform": "instagram",
      "aspect_ratio": {
        "ratio": "1:1",
        "width": 1080,
        "height": 1080,
        "label": "Square"
      },
      "description": "Perfect for Instagram feed posts with maximum visibility",
      "recommended_provider": "ideogram",
      "style_preset": "photographic",
      "quality": "premium",
      "use_cases": ["Product showcase", "Lifestyle posts", "Brand content"]
    }
    // ... 3 more Instagram templates
  ],
  "total": 4
}

Example 4: Search Templates

Request:

GET /api/image-studio/templates/search?query=product

Result: Returns all templates with "product" in name, description, or use cases.

Example 5: Cost Estimation

Request:

POST /api/image-studio/estimate-cost
{
  "provider": "wavespeed",
  "model": "ideogram-v3-turbo",
  "operation": "generate",
  "num_images": 10,
  "width": 1080,
  "height": 1080
}

Response:

{
  "provider": "wavespeed",
  "model": "ideogram-v3-turbo",
  "operation": "generate",
  "num_images": 10,
  "resolution": "1080x1080",
  "cost_per_image": 0.10,
  "total_cost": 1.00,
  "currency": "USD",
  "estimated": true
}

---

🎨 Frontend Integration (Next Step)

What to Build

Create a React component at: frontend/src/components/ImageStudio/CreateStudio.tsx

Component Structure

import React, { useState } from 'react';

interface CreateStudioProps {
  // Your props
}

export const CreateStudio: React.FC<CreateStudioProps> = () => {
  const [prompt, setPrompt] = useState('');
  const [templateId, setTemplateId] = useState<string | null>(null);
  const [quality, setQuality] = useState<'draft' | 'standard' | 'premium'>('standard');
  const [loading, setLoading] = useState(false);
  const [results, setResults] = useState<any[]>([]);

  // Fetch templates on mount
  useEffect(() => {
    fetchTemplates();
  }, []);

  const fetchTemplates = async () => {
    const response = await fetch('/api/image-studio/templates');
    const data = await response.json();
    setTemplates(data.templates);
  };

  const generateImage = async () => {
    setLoading(true);
    try {
      const response = await fetch('/api/image-studio/create', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          prompt,
          template_id: templateId,
          quality,
          num_variations: 1
        })
      });
      const data = await response.json();
      setResults(data.results);
    } catch (error) {
      console.error('Generation failed:', error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div className="create-studio">
      <h2>Create Studio</h2>
      
      {/* Template Selector */}
      <TemplateSelector 
        templates={templates} 
        selected={templateId}
        onSelect={setTemplateId}
      />
      
      {/* Prompt Input */}
      <textarea
        value={prompt}
        onChange={(e) => setPrompt(e.target.value)}
        placeholder="Describe your image..."
      />
      
      {/* Quality Selector */}
      <select value={quality} onChange={(e) => setQuality(e.target.value)}>
        <option value="draft">Draft (Fast)</option>
        <option value="standard">Standard</option>
        <option value="premium">Premium (Best Quality)</option>
      </select>
      
      {/* Generate Button */}
      <button onClick={generateImage} disabled={loading || !prompt}>
        {loading ? 'Generating...' : 'Generate Image'}
      </button>
      
      {/* Results */}
      {results.map((result, idx) => (
        <img 
          key={idx}
          src={`data:image/png;base64,${result.image_base64}`}
          alt={`Generated ${idx + 1}`}
        />
      ))}
    </div>
  );
};

Key UI Elements Needed

1. Template Selector: Grid or dropdown of templates
2. Prompt Input: Textarea with character counter
3. Provider Selector: Optional, defaults to "auto"
4. Quality Selector: Draft, Standard, Premium
5. Advanced Options: Collapsible section for dimensions, style, negative prompt
6. Cost Display: Show estimated cost before generation
7. Generate Button: Prominent CTA
8. Results Gallery: Display generated images
9. Download/Save: Actions for generated images

---

📋 Checklist for Integration

Backend Setup

• Create backend services
• Create API endpoints
• Add WaveSpeed provider
• Create template system
• Add environment variable WAVESPEED_API_KEY
• Register router in app.py
• Test API endpoints

Frontend Development

• Create CreateStudio.tsx component
• Create TemplateSelector.tsx component
• Create hooks: useImageGeneration.ts
• Add API client functions
• Implement template browsing
• Implement image generation
• Add results display
• Add cost estimation display
• Add error handling
• Add loading states

Pre-flight Validation

• Integrate with subscription service
• Check user tier before generation
• Display remaining credits
• Enforce usage limits
• Show upgrade prompts if needed

Testing

• Test with each provider
• Test all templates
• Test error scenarios
• Test multiple variations
• Test cost calculations
• Performance testing

---

🔥 Quick Demo Script

# 1. Set environment variable
export WAVESPEED_API_KEY=your_key_here

# 2. Start backend
cd backend
python app.py

# 3. Test health
curl http://localhost:8000/api/image-studio/health

# 4. Get Instagram templates
curl http://localhost:8000/api/image-studio/templates?platform=instagram | jq

# 5. Generate an image (replace YOUR_TOKEN)
curl -X POST http://localhost:8000/api/image-studio/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Modern coffee shop interior, cozy and inviting",
    "template_id": "instagram_feed_square",
    "quality": "standard",
    "num_variations": 1
  }' | jq

# 6. View result (image will be in base64)
# Copy the image_base64 value and decode it or use an online base64 decoder

---

🎯 Success Metrics

Backend (✅ Complete)

• All API endpoints functional
• 5 providers integrated
• 27 templates available
• Smart provider selection working
• Cost estimation functional
• Error handling comprehensive

Frontend (⏳ Next)

• Component renders without errors
• Templates load and display correctly
• Image generation works
• Results display properly
• Cost estimation shows before generation
• Error messages are clear

End-to-End (⏳ After Frontend)

• User can select template
• User can generate image
• Image displays correctly
• User can download image
• Cost tracking works
• All providers functional

---

💡 Pro Tips

1. Start Simple: Build basic UI first (prompt + button), add features incrementally
2. Use Templates: Template system makes it easy - let users pick template instead of dimensions
3. Show Costs: Always display estimated cost before generation
4. Handle Errors: Wrap API calls in try-catch, show user-friendly messages
5. Loading States: Show spinner/progress during generation (takes 2-10 seconds)
6. Cache Templates: Fetch templates once, cache in component state
7. Auto-Save: Save generated images to asset library automatically
8. Keyboard Shortcuts: Cmd/Ctrl+Enter to generate, Cmd/Ctrl+S to save

---

📚 Documentation Links

• Comprehensive Plan - Full feature specifications
• Implementation Summary - What was built
• Quick Start Guide - Developer reference
• Executive Summary - Business case

---

🆘 Need Help?

Common Issues

Issue: WAVESPEED_API_KEY not found
Solution: Add to .env file and restart backend

Issue: Router not found
Solution: Add app.include_router(image_studio.router) to app.py

Issue: Templates not loading
Solution: Check /api/image-studio/health endpoint first

Issue: Image generation fails
Solution: Check logs for provider-specific errors, verify API keys

---

🎉 You're Ready!

The backend is complete and production-ready. All you need to do is:

1. ✅ Add WAVESPEED_API_KEY to .env
2. ✅ Register router in app.py
3. ✅ Build the frontend component
4. ✅ Test end-to-end
5. ✅ Deploy!

Happy Building! 🚀

---

Last Updated: January 2025
Version: 1.0
Status: Backend Ready for Frontend Integration