DEV Community: ImaginePro

Complete Beginner's Guide to use Midjourney API to Create AI Images with Python

ImaginePro — Fri, 08 Aug 2025 09:05:49 +0000

Are you a Python beginner who wants to create stunning AI-generated images using Midjourney's powerful AI models? Look no further! This comprehensive guide will walk you through everything you need to know about using Midjourney's capabilities through ImaginePro's unofficial API, from installation to advanced features.

What is Midjourney and ImaginePro?

Midjourney is one of the most powerful AI image generation platforms, known for its exceptional artistic quality and creative capabilities. However, Midjourney doesn't provide official APIs for developers.

ImaginePro bridges this gap by offering an unofficial API that gives you programmatic access to Midjourney's image generation capabilities. With the ImaginePro Python SDK, you can:

🎨 Generate high-quality Midjourney-style images from text descriptions
⚡ Upscale images while maintaining Midjourney's quality standards
🔄 Create variants of existing images
🎯 Modify specific areas of images (inpainting)
📡 Receive real-time progress updates
🔗 Integrate Midjourney capabilities into your applications via webhooks

Prerequisites

Before we start, make sure you have:

Python 3.7+ installed on your system
An ImaginePro API key (get one from platform.imaginepro.ai) - This gives you access to Midjourney's capabilities
Basic Python knowledge (variables, functions, imports)
Understanding: This guide uses ImaginePro's unofficial API to access Midjourney's image generation features

Installation

Getting started is super easy! Open your terminal and run:

pip install imaginepro

That's it! The SDK is now ready to use.

Your First Midjourney-Style Image Generation

Let's start with a simple example that will generate your first Midjourney-style AI image:

import os
from imaginepro import ImagineProSDK, ImagineProSDKOptions

# Step 1: Set up your API key
# Replace 'your-api-key-here' with your actual API key
API_KEY = "your-api-key-here"

# Step 2: Initialize the SDK
sdk = ImagineProSDK(ImagineProSDKOptions(
    api_key=API_KEY,
    base_url="https://api.imaginepro.ai",  # Optional: default URL
    default_timeout=300,  # Optional: 5 minutes timeout
    fetch_interval=2,  # Optional: check status every 2 seconds
))

    # Step 3: Generate your first Midjourney-style image
    try:
        print("🚀 Starting Midjourney-style image generation...")

        # Create an image generation request using Midjourney's capabilities
        result = sdk.imagine({
            "prompt": "a cute cat playing with a ball of yarn in a sunny garden --ar 16:9 --v 6"
        })

        print(f"✅ Generation initiated! Message ID: {result['messageId']}")

        # Step 4: Wait for the image to be ready
        print("⏳ Waiting for Midjourney generation to complete...")
        final_result = sdk.fetch_message(result["messageId"])

        # Step 5: Display the result
        if final_result["status"] == "DONE":
            print(f"🎉 Midjourney-style image generated successfully!")
            print(f"📸 Image URL: {final_result['uri']}")
            print(f"📝 Prompt used: {final_result['prompt']}")
        else:
            print(f"❌ Generation failed: {final_result.get('error', 'Unknown error')}")

    except Exception as error:
        print(f"❌ Error: {error}")

Save this code in a file (e.g., first_midjourney_image.py) and run it. You'll see your first Midjourney-style AI-generated image!

Understanding the Polling Process

One of the key features of the ImaginePro SDK is its polling mechanism for Midjourney image generation. Let's break down how it works:

What is Polling?

Polling means the SDK automatically checks the status of your Midjourney image generation until it's complete. Here's what happens:

Submit Request: You send a prompt to generate a Midjourney-style image
Get Message ID: The API returns a unique message ID
Poll for Status: The SDK repeatedly checks if the Midjourney generation is ready
Return Result: Once complete, you get the final image URL

Customizing Polling Behavior

You can control how the polling works:

# Example with custom polling settings
final_result = sdk.fetch_message(
    message_id=result["messageId"],
    interval=1,    # Check every 1 second (default: 2 seconds)
    timeout=600    # Wait up to 10 minutes (default: 30 minutes)
)

Manual Polling (Advanced)

If you want more control, you can poll manually:

import time

# Get the initial message ID
result = sdk.imagine({"prompt": "a beautiful sunset over mountains --ar 16:9 --v 6"})
message_id = result["messageId"]

# Manual polling loop
while True:
    # Check the current status
    status = sdk.fetch_message_once(message_id)

    print(f"Status: {status['status']}, Progress: {status['progress']}%")

    # Check if generation is complete
    if status['status'] == 'DONE':
        print(f"🎉 Midjourney image ready: {status['uri']}")
        break
    elif status['status'] == 'FAIL':
        print(f"❌ Generation failed: {status.get('error', 'Unknown error')}")
        break

    # Wait before checking again
    time.sleep(2)

Core Features Explained

1. Basic Midjourney Image Generation

The imagine method is your main tool for creating Midjourney-style images:

# Simple Midjourney image generation
result = sdk.imagine({
    "prompt": "a futuristic city at night with neon lights --ar 16:9 --v 6"
})

# Advanced Midjourney image generation with parameters
result = sdk.imagine({
    "prompt": "a majestic dragon flying over a castle, epic fantasy art --ar 16:9 --v 6 --q 2",
    "negative_prompt": "blurry, low quality, distorted",
    "width": 1024,
    "height": 768,
    "steps": 50,
    "cfg_scale": 7.5,
    "style": "photorealistic"
})

Parameters Explained:

prompt: What you want to see in the image (supports Midjourney parameters like --ar 16:9, --v 6, --q 2)
negative_prompt: What you DON'T want to see
width/height: Image dimensions (in pixels)
steps: Generation quality (higher = better but slower)
cfg_scale: How closely to follow your prompt (1-20)
style: Artistic style (e.g., "photorealistic", "artistic")

2. Image Upscaling

Make your images higher resolution:

# Upscale the first image in a set (U1 button)
upscale_result = sdk.upscale({
    "message_id": "your-message-id",
    "index": 1  # Corresponds to U1 button
})

# Wait for upscaling to complete
final_upscale = sdk.fetch_message(upscale_result["messageId"])
print(f"Upscaled image: {final_upscale['uri']}")

3. Creating Image Variants

Generate different versions of the same image:

# Create a variant of the first image (V1 button)
variant_result = sdk.variant({
    "message_id": "your-message-id",
    "index": 1  # Corresponds to V1 button
})

# Wait for variant generation
final_variant = sdk.fetch_message(variant_result["messageId"])
print(f"Variant image: {final_variant['uri']}")

4. Regenerating Images (Reroll)

Try again with the same prompt:

# Regenerate the image with the same prompt
reroll_result = sdk.reroll({
    "message_id": "your-message-id"
})

# Wait for regeneration
final_reroll = sdk.fetch_message(reroll_result["messageId"])
print(f"Rerolled image: {final_reroll['uri']}")

5. Inpainting (Advanced)

Modify specific areas of an image:

# Inpaint a specific region
inpaint_result = sdk.inpainting({
    "message_id": "your-message-id",
    "mask": "your-mask-data",  # Create mask at https://mask.imaginepro.ai/
    "prompt": "a beautiful flower garden"
})

# Wait for inpainting
final_inpaint = sdk.fetch_message(inpaint_result["messageId"])
print(f"Inpainted image: {final_inpaint['uri']}")

Working with Message Responses

Every operation returns a MessageResponse with useful information:

# Example of a complete message response
message_response = {
    "messageId": "abc123def456",
    "prompt": "a cute cat playing with yarn",
    "uri": "https://cdn.imaginepro.ai/generated-image.jpg",
    "progress": 100,
    "status": "DONE",  # Can be: PROCESSING, QUEUED, DONE, FAIL
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:32:00Z",
    "buttons": ["U1", "V1", "V2", "V3", "V4"],  # Available actions
    "ref": "my-custom-reference",
    "error": None  # Will contain error message if status is FAIL
}

Webhook Integration

For production applications, you can use webhooks to receive notifications:

# Generate image with webhook
result = sdk.imagine({
    "prompt": "a magical forest scene",
    "ref": "forest-generation-001",  # Custom reference ID
    "webhook_override": "https://your-server.com/webhook"  # Your webhook URL
})

When the image is ready, ImaginePro will send a POST request to your webhook URL with the complete result.

Error Handling Best Practices

Always handle errors gracefully:

try:
    # Generate image
    result = sdk.imagine({"prompt": "a beautiful landscape"})

    # Wait for completion
    final_result = sdk.fetch_message(result["messageId"])

    if final_result["status"] == "DONE":
        print(f"✅ Success: {final_result['uri']}")
    else:
        print(f"❌ Failed: {final_result.get('error', 'Unknown error')}")

except TimeoutError:
    print("⏰ Generation timed out. Try again later.")
except Exception as e:
    print(f"❌ Unexpected error: {e}")

Complete Example: Image Generation Workflow

Here's a complete example that demonstrates a typical workflow:

import os
from imaginepro import ImagineProSDK, ImagineProSDKOptions

def generate_and_process_image():
    # Initialize SDK
    sdk = ImagineProSDK(ImagineProSDKOptions(
        api_key="your-api-key-here",
        default_timeout=600,  # 10 minutes
        fetch_interval=1      # Check every second
    ))

    try:
        # Step 1: Generate initial Midjourney-style image
        print("🎨 Generating initial Midjourney-style image...")
        initial_result = sdk.imagine({
            "prompt": "a serene lake with mountains in the background at sunset, landscape photography --ar 16:9 --v 6",
            "width": 1024,
            "height": 768
        })

        # Step 2: Wait for completion
        print("⏳ Waiting for generation...")
        final_initial = sdk.fetch_message(initial_result["messageId"])

        if final_initial["status"] != "DONE":
            print(f"❌ Initial generation failed: {final_initial.get('error')}")
            return

        print(f"✅ Initial image ready: {final_initial['uri']}")

        # Step 3: Create a variant
        print("🔄 Creating a variant...")
        variant_result = sdk.variant({
            "message_id": final_initial["messageId"],
            "index": 1
        })

        final_variant = sdk.fetch_message(variant_result["messageId"])

        if final_variant["status"] == "DONE":
            print(f"✅ Variant ready: {final_variant['uri']}")

        # Step 4: Upscale the best image
        print("📈 Upscaling the variant...")
        upscale_result = sdk.upscale({
            "message_id": final_variant["messageId"],
            "index": 1
        })

        final_upscale = sdk.fetch_message(upscale_result["messageId"])

        if final_upscale["status"] == "DONE":
            print(f"✅ Final upscaled image: {final_upscale['uri']}")
            print("🎉 Workflow completed successfully!")

    except Exception as e:
        print(f"❌ Error in workflow: {e}")

# Run the workflow
if __name__ == "__main__":
    generate_and_process_image()

Tips for Beginners

Start Simple: Begin with basic prompts before adding Midjourney parameters
Learn Midjourney Syntax: Use parameters like --ar 16:9 (aspect ratio), --v 6 (version), --q 2 (quality)
Be Patient: Midjourney image generation can take 30 seconds to several minutes
Use Descriptive Prompts: The more detailed your prompt, the better the Midjourney result
Experiment: Try different Midjourney styles, settings, and prompts
Handle Errors: Always wrap your code in try-catch blocks
Monitor Progress: Use the polling features to track Midjourney generation status

Common Issues and Solutions

Issue: "Timeout exceeded"

Solution: Increase the timeout value or check your internet connection

Issue: "Invalid API key"

Solution: Verify your API key is correct and has sufficient credits

Issue: "Generation failed"

Solution: Try a different prompt or check the error message for details

Issue: "Rate limit exceeded"

Solution: Wait a few minutes before making another request

Next Steps

Now that you've mastered the basics, you can:

Build a Web Application: Create a Flask or FastAPI app with image generation
Batch Processing: Generate multiple images in sequence
Image Editing Pipeline: Combine generation with upscaling and variants
Integration: Add AI image generation to your existing projects

Resources

ImaginePro Platform - Get your API key for Midjourney access
API Documentation - Official ImaginePro API docs
Mask Tool for Inpainting - Create masks for inpainting
GitHub Repository - SDK source code
Midjourney Official Site - Learn about Midjourney's capabilities

Happy coding! 🚀

This guide covers using Midjourney's capabilities through ImaginePro's unofficial API. For the latest updates, check the official documentation.

Complete Guide to Use Midjourney API for Text-to-Image Generation

ImaginePro — Wed, 06 Aug 2025 11:18:10 +0000

Building a Text-to-Image Tool with Midjourney API

Introduction

Midjourney has revolutionized the world of AI-generated imagery with its powerful text-to-image capabilities. While Midjourney is primarily known for its Discord bot interface, developers can now integrate its image generation capabilities directly into their applications using APIs. This guide will walk you through everything you need to know to build a text-to-image tool using Midjourney's API.

Prerequisites

Before diving into the implementation, ensure you have:

Basic knowledge of JavaScript/TypeScript
Node.js installed on your system
An API key
Understanding of REST APIs and asynchronous programming

Getting Started

1. Installation

First, install the necessary SDK. For this guide, we'll use the ImaginePro SDK which provides a clean interface for Midjourney API interactions:

npm install imaginepro

2. Basic Setup

Create a new project and set up the basic configuration:

import ImagineProSDK from 'imaginepro';

const midjourneyClient = new ImagineProSDK({
    apiKey: 'your-imaginepro-api-key',
});

Core Functionality

Text-to-Image Generation

The primary feature is generating images from text prompts:

async function generateImage(prompt) {
    try {
        // Initiate image generation
        const response = await midjourneyClient.imagine({
            prompt: prompt,
        });

        console.log('Generation started:', response.messageId);

        // Wait for completion and get result
        const result = await midjourneyClient.fetchMessage(response.messageId);

        return result;
    } catch (error) {
        console.error('Generation failed:', error);
        throw error;
    }
}

// Usage example
const imageResult = await generateImage('a majestic dragon flying over a medieval castle at sunset');
console.log('Generated image URL:', imageResult.uri);

Advanced Prompt Engineering

Midjourney responds well to detailed, descriptive prompts. Here are some best practices:

// Good prompt structure
const goodPrompt = 'a photorealistic portrait of a wise old wizard, dramatic lighting, intricate details, 8k resolution, cinematic composition';

// Include style modifiers
const styledPrompt = 'a futuristic cityscape, cyberpunk aesthetic, neon lights, rain-slicked streets, cinematic lighting';

// Specify aspect ratios and quality
const detailedPrompt = 'a serene mountain landscape at golden hour, 16:9 aspect ratio, high quality, detailed textures';

Image Manipulation Features

Upscaling Images

Enhance the resolution of generated images:

async function upscaleImage(messageId, index = 1) {
    try {
        const result = await midjourneyClient.upscale({
            messageId: messageId,
            index: index // Corresponds to U1, U2, U3, U4 buttons
        });

        return result;
    } catch (error) {
        console.error('Upscaling failed:', error);
        throw error;
    }
}

Generating Variants

Create alternative versions of existing images:

async function createVariant(messageId, index = 1) {
    try {
        const result = await midjourneyClient.variant({
            messageId: messageId,
            index: index // Corresponds to V1, V2, V3, V4 buttons
        });

        return result;
    } catch (error) {
        console.error('Variant generation failed:', error);
        throw error;
    }
}

Rerolling Images

Regenerate images with the same prompt:

async function rerollImage(messageId) {
    try {
        const result = await midjourneyClient.reroll({
            messageId: messageId
        });

        return result;
    } catch (error) {
        console.error('Reroll failed:', error);
        throw error;
    }
}

Building a Complete Text-to-Image Tool

1. Create the Main Application

class TextToImageTool {
    constructor(apiKey) {
        this.client = new ImagineProSDK({
            apiKey: apiKey,
            timeout: 300000,
        });
        this.generationHistory = [];
    }

    async generateImage(prompt, options = {}) {
        const generationId = Date.now().toString();

        try {
            // Start generation
            const response = await this.client.imagine({
                prompt: prompt,
                ref: generationId,
                webhookOverride: options.webhookUrl
            });

            // Track generation
            this.generationHistory.push({
                id: generationId,
                messageId: response.messageId,
                prompt: prompt,
                status: 'processing',
                startTime: new Date()
            });

            // Wait for completion
            const result = await this.client.fetchMessage(response.messageId);

            // Update history
            const historyItem = this.generationHistory.find(item => item.id === generationId);
            if (historyItem) {
                historyItem.status = result.status;
                historyItem.result = result;
                historyItem.completionTime = new Date();
            }

            return result;
        } catch (error) {
            console.error('Image generation failed:', error);
            throw error;
        }
    }

    async enhanceImage(messageId, enhancementType, index = 1) {
        switch (enhancementType) {
            case 'upscale':
                return await this.client.upscale({ messageId, index });
            case 'variant':
                return await this.client.variant({ messageId, index });
            case 'reroll':
                return await this.client.reroll({ messageId });
            default:
                throw new Error('Unknown enhancement type');
        }
    }

    getGenerationHistory() {
        return this.generationHistory;
    }
}

2. Webhook Integration

For production applications, use webhooks to handle generation results asynchronously:

// Set up webhook endpoint
app.post('/webhook/midjourney', (req, res) => {
    const { messageId, status, uri, prompt, ref } = req.body;

    if (status === 'DONE') {
        // Handle successful generation
        console.log(`Image generated for prompt: ${prompt}`);
        console.log(`Image URL: ${uri}`);

        // Update your database, send notifications, etc.
        updateUserGallery(ref, uri);
    } else if (status === 'FAIL') {
        // Handle failed generation
        console.error(`Generation failed for prompt: ${prompt}`);
        notifyUserOfFailure(ref);
    }

    res.status(200).send('OK');
});

// Use webhook in generation
const result = await tool.generateImage('a beautiful sunset', {
    webhookUrl: 'https://your-app.com/webhook/midjourney'
});

3. Error Handling and Retry Logic

async function generateWithRetry(prompt, maxRetries = 3) {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
        try {
            return await tool.generateImage(prompt);
        } catch (error) {
            console.error(`Attempt ${attempt} failed:`, error.message);

            if (attempt === maxRetries) {
                throw new Error(`Failed after ${maxRetries} attempts: ${error.message}`);
            }

            // Wait before retrying
            await new Promise(resolve => setTimeout(resolve, 2000 * attempt));
        }
    }
}

Best Practices

1. Prompt Optimization

Be specific: Instead of "a cat", use "a majestic Persian cat with golden fur sitting in a sunlit garden"
Include style keywords: "photorealistic", "cinematic", "artistic", "minimalist"
Specify lighting and mood: "dramatic lighting", "soft natural light", "moody atmosphere"
Add quality modifiers: "high resolution", "detailed", "8k", "professional photography"

2. Performance Optimization

// Batch processing for multiple images
async function generateBatch(prompts) {
    const promises = prompts.map(prompt => 
        tool.generateImage(prompt).catch(error => ({
            error: error.message,
            prompt: prompt
        }))
    );

    return await Promise.allSettled(prompts);
}

// Rate limiting
class RateLimitedGenerator {
    constructor(tool, maxRequestsPerMinute = 10) {
        this.tool = tool;
        this.maxRequests = maxRequestsPerMinute;
        this.requestQueue = [];
        this.lastRequestTime = 0;
    }

    async generateImage(prompt) {
        const now = Date.now();
        const timeSinceLastRequest = now - this.lastRequestTime;
        const minInterval = 60000 / this.maxRequests; // 60 seconds / max requests

        if (timeSinceLastRequest < minInterval) {
            await new Promise(resolve => 
                setTimeout(resolve, minInterval - timeSinceLastRequest)
            );
        }

        this.lastRequestTime = Date.now();
        return await this.tool.generateImage(prompt);
    }
}

3. User Experience Considerations

// Progress tracking
async function generateWithProgress(prompt, onProgress) {
    const response = await tool.client.imagine({ prompt });

    // Poll for progress
    const checkProgress = async () => {
        const result = await tool.client.fetchMessage(response.messageId);

        onProgress({
            status: result.status,
            progress: result.progress,
            messageId: response.messageId
        });

        if (result.status === 'PROCESSING' || result.status === 'QUEUED') {
            setTimeout(checkProgress, 2000);
        }
    };

    checkProgress();
    return await tool.client.fetchMessage(response.messageId);
}

// Usage
generateWithProgress('a magical forest', (progress) => {
    console.log(`Status: ${progress.status}, Progress: ${progress.progress}%`);
});

Advanced Features

Inpainting (Selective Editing)

async function inpaintImage(messageId, mask) {
    try {
        const result = await midjourneyClient.inpainting({
            messageId: messageId,
            mask: mask // Base64 encoded mask image
        });

        return result;
    } catch (error) {
        console.error('Inpainting failed:', error);
        throw error;
    }
}

Custom Webhook Handling

class WebhookHandler {
    constructor() {
        this.pendingGenerations = new Map();
    }

    registerGeneration(generationId, callback) {
        this.pendingGenerations.set(generationId, callback);
    }

    handleWebhook(payload) {
        const { ref, status, uri, error } = payload;
        const callback = this.pendingGenerations.get(ref);

        if (callback) {
            callback({ status, uri, error });
            this.pendingGenerations.delete(ref);
        }
    }
}

Troubleshooting Common Issues

1. API Rate Limits

// Implement exponential backoff
async function generateWithBackoff(prompt, maxRetries = 5) {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
        try {
            return await tool.generateImage(prompt);
        } catch (error) {
            if (error.message.includes('rate limit')) {
                const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
                console.log(`Rate limited, waiting ${delay}ms before retry`);
                await new Promise(resolve => setTimeout(resolve, delay));
            } else {
                throw error;
            }
        }
    }
}

2. Network Issues

// Add timeout and retry for network issues
const clientWithRetry = new ImagineProSDK({
    apiKey: 'your-api-key',
    timeout: 60000, // 1 minute timeout
    retryAttempts: 3,
    retryDelay: 1000
});

Conclusion

Building a text-to-image tool with Midjourney API opens up incredible possibilities for creative applications. By following this guide, you'll have a solid foundation for creating robust, user-friendly image generation tools.

Remember to:

Always handle errors gracefully
Implement proper rate limiting
Use webhooks for production applications
Optimize prompts for better results
Monitor API usage and costs

The ImaginePro SDK provides a clean, professional interface for Midjourney API integration, making it easier to build enterprise-grade applications with reliable image generation capabilities.

DEV Community: ImaginePro

Complete Beginner's Guide to use Midjourney API to Create AI Images with Python

What is Midjourney and ImaginePro?

Prerequisites

Installation

Your First Midjourney-Style Image Generation

Understanding the Polling Process

What is Polling?

Customizing Polling Behavior

Manual Polling (Advanced)

Core Features Explained

1. Basic Midjourney Image Generation

2. Image Upscaling

3. Creating Image Variants

4. Regenerating Images (Reroll)

5. Inpainting (Advanced)

Working with Message Responses

Webhook Integration

Error Handling Best Practices

Complete Example: Image Generation Workflow

Tips for Beginners

Common Issues and Solutions

Issue: "Timeout exceeded"

Issue: "Invalid API key"

Issue: "Generation failed"

Issue: "Rate limit exceeded"

Next Steps

Resources

Complete Guide to Use Midjourney API for Text-to-Image Generation

Building a Text-to-Image Tool with Midjourney API

Introduction

Prerequisites

Getting Started

1. Installation

2. Basic Setup

Core Functionality

Text-to-Image Generation

Advanced Prompt Engineering

Image Manipulation Features

Upscaling Images

Generating Variants

Rerolling Images

Building a Complete Text-to-Image Tool

1. Create the Main Application

2. Webhook Integration

3. Error Handling and Retry Logic

Best Practices

1. Prompt Optimization

2. Performance Optimization

3. User Experience Considerations

Advanced Features

Inpainting (Selective Editing)

Custom Webhook Handling

Troubleshooting Common Issues

1. API Rate Limits

2. Network Issues

Conclusion

Additional Resources