Professional API Reference

https://gemimg.art/api/v1

Authorization: Bearer YOUR_PROFESSIONAL_API_KEY

POST /api/v1/professional/generate

{
  "prompt": "Modern minimalist villa exterior, Nordic design aesthetic, blue hour, interior warm light contrast, f/11 depth of field, 4K ultra-HD",
  "negativePrompt": "blurry, noise, overexposed, distortion",
  "mode": "text_to_image",
  "resolution": "4K",
  "outputFormat": "png",
  "aspectRatio": "16:9",
  "colorSpace": "Adobe_RGB",
  "seed": 12345,
  "styleStrength": 0.8,
  "priority": "high"
}

{
  "success": true,
  "taskId": "prof_task_abc123xyz",
  "status": "queued",
  "priority": "high",
  "estimatedTime": 55,
  "creditsUsed": 3,
  "webhook": "https://your-domain.com/callback"
}

POST /api/v1/professional/transform

{
  "prompt": "Commercial fashion photography lighting, professional retouching, 85mm portrait lens, Rembrandt lighting",
  "mode": "image_transformation",
  "referenceImages": [
    {
      "url": "https://storage.your-domain.com/reference/arch_001.raw",
      "weight": 0.75,
      "format": "RAW"
    }
  ],
  "resolution": "4K",
  "outputFormat": "png",
  "colorGrading": "cinema",
  "preserveDetails": true
}

GET /api/v1/tasks/{taskId}

{
  "success": true,
  "taskId": "prof_task_abc123xyz",
  "status": "completed",
  "result": {
    "imageUrl": "https://cdn.gemimg.top/professional/4k_abc123.png",
    "thumbnailUrl": "https://cdn.gemimg.top/professional/4k_abc123_thumb.jpg",
    "resolution": "3840x2160",
    "fileSize": "12.4 MB",
    "colorSpace": "Adobe_RGB",
    "metadata": {
      "renderTime": 58,
      "creditsUsed": 3,
      "seed": 12345
    }
  }
}

POST /api/v1/professional/batch

{
  "tasks": [
    {
      "prompt": "Architectural visualization A - exterior perspective",
      "resolution": "4K",
      "priority": "high"
    },
    {
      "prompt": "Architectural visualization B - interior space",
      "resolution": "4K",
      "priority": "normal"
    }
  ],
  "batchOptions": {
    "parallel": true,
    "maxConcurrent": 5,
    "webhook": "https://your-domain.com/batch-callback"
  }
}

{
  "success": true,
  "batchId": "batch_xyz789",
  "totalTasks": 50,
  "status": "processing",
  "estimatedCompletion": "2024-01-15T10:30:00Z"
}

POST /api/v1/webhooks/register

{
  "url": "https://your-domain.com/gemimg-webhook",
  "events": ["task.completed", "task.failed", "batch.completed"],
  "secret": "your_webhook_secret"
}

{
  "event": "task.completed",
  "timestamp": "2024-01-15T10:25:30Z",
  "data": {
    "taskId": "prof_task_abc123xyz",
    "status": "completed",
    "imageUrl": "https://cdn.gemimg.top/professional/4k_abc123.png",
    "creditsUsed": 3
  },
  "signature": "sha256=abc123..."
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits in professional account",
    "details": {
      "required": 3,
      "available": 1
    }
  }
}

const GemimgPro = require('@gemimg/professional-sdk');

const client = new GemimgPro({
  apiKey: 'YOUR_PROFESSIONAL_API_KEY',
  baseURL: 'https://gemimg.art/api/v1'
});

async function generateProfessionalImage() {
  try {
    const task = await client.textToImage.create({
      prompt: 'Commercial product photography, studio lighting, 85mm lens, f/2.8, 4K',
      resolution: '4K',
      outputFormat: 'png',
      colorSpace: 'Adobe_RGB',
      priority: 'high'
    });
    
    console.log('Task created:', task.taskId);
    
    // Poll for completion
    const result = await client.tasks.waitForCompletion(task.taskId);
    console.log('Image URL:', result.imageUrl);
    
  } catch (error) {
    console.error('Error:', error.message);
  }
}

generateProfessionalImage();

from gemimg_pro import GemimgProfessional

client = GemimgProfessional(
    api_key='YOUR_PROFESSIONAL_API_KEY',
    base_url='https://gemimg.art/api/v1'
)

def generate_professional_image():
    try:
        # Create task
        task = client.text_to_image.create(
            prompt='Architectural visualization, photorealistic rendering, blue hour, 4K',
            resolution='4K',
            output_format='png',
            color_space='Adobe_RGB',
            priority='high'
        )
        
        print(f'Task created: {task.task_id}')
        
        # Wait for completion
        result = client.tasks.wait_for_completion(task.task_id, timeout=120)
        print(f'Image URL: {result.image_url}')
        
    except GemimgProError as e:
        print(f'Error: {e.message}')

generate_professional_image()

# Create professional text-to-image task
curl -X POST https://gemimg.art/api/v1/professional/generate \
  -H "Authorization: Bearer YOUR_PROFESSIONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Fashion photography, studio lighting, professional retouching, 4K",
    "resolution": "4K",
    "outputFormat": "png",
    "priority": "high"
  }'

# Query task status
curl -X GET https://gemimg.art/api/v1/tasks/prof_task_abc123xyz \
  -H "Authorization: Bearer YOUR_PROFESSIONAL_API_KEY"

// ✅ Good - Professional terminology
const prompt = "Commercial product photography, studio lighting setup, 85mm f/1.8 lens, shallow depth of field, professional color grading, 4K resolution";

// ❌ Avoid - Generic descriptions
const prompt = "nice product photo";

# Check available credits
credits = client.account.get_credits()
required = len(batch_tasks) * 3  # 3 credits per 4K image

if credits.available < required:
    print(f"Insufficient credits: {credits.available}/{required}")
    # Purchase more or adjust batch size

app.post('/gemimg-webhook', (req, res) => {
  const signature = req.headers['x-gemimg-signature'];
  
  // Verify webhook signature
  if (!verifySignature(req.body, signature, webhookSecret)) {
    return res.status(401).send('Invalid signature');
  }
  
  const { event, data } = req.body;
  
  if (event === 'task.completed') {
    // Download and process completed image
    downloadImage(data.imageUrl);
  }
  
  res.status(200).send('OK');
});

import time

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.text_to_image.create(prompt=prompt)
        except RateLimitError:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # 1s, 2s, 4s
                time.sleep(wait_time)
            else:
                raise

// Only need to update the API key and base URL
const client = new GemimgPro({
  apiKey: 'YOUR_PROFESSIONAL_API_KEY',  // New key
  baseURL: 'https://gemimg.art/api/v1'  // Professional endpoint
});

// All existing code remains compatible
// + Access to 4K, batch processing, webhooks