LogoGempix2 AI

API Reference

Complete API documentation for Gempix2 AI image generation

Overview

The Gempix2 AI API allows you to programmatically generate AI images from text descriptions or images. Our RESTful API is designed to be simple, powerful, and easy to integrate into your applications.

Base URL

https://gempix2ai.site/api

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can generate API keys from your account dashboard.

Generate Image

Create a new AI image from text or image.

Endpoint

POST /generate-image

Request Body

{
  "generationType": "text_to_image" - "image_to_image",
  "prompt": "Your image description",
  "aspectRatio": "auto" - "16:9" - "9:16" - "1:1",
  "imageUrl": "https://...", // Required if generationType is "image_to_image"
  "imageKey": "r2-key" // Optional, for uploaded images
}

Parameters

| Parameter - Type - Required - Description | |-----------|------|----------|-------------| | generationType - string - Yes - Type of generation: text_to_image or image_to_image | | prompt - string - Yes - Description of the image you want to generate | | aspectRatio - string - No - Image aspect ratio. Default: auto | | imageUrl - string - Conditional - Required if generationType is image_to_image | | imageKey - string - No - Storage key for uploaded images |

Response

{
  "code": 0,
  "msg": "Success",
  "data": {
    "uuid": "image-uuid-123",
    "status": "pending",
    "generationType": "text_to_image",
    "prompt": "Your image description",
    "aspectRatio": "16:9",
    "createdAt": "2025-10-16T10:00:00Z"
  }
}

Example

curl -X POST https://gempix2ai.site/api/generate-image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "generationType": "text_to_image",
    "prompt": "A beautiful sunset over the ocean with waves gently lapping the shore",
    "aspectRatio": "16:9"
  }'

Get Image Status

Check the status of an image generation request.

Endpoint

GET /image-status/{uuid}

Parameters

| Parameter - Type - Required - Description | |-----------|------|----------|-------------| | uuid - string - Yes - Image UUID from generation request |

Response

{
  "code": 0,
  "msg": "Success",
  "data": {
    "uuid": "image-uuid-123",
    "status": "completed" - "pending" - "processing" - "failed",
    "imageUrl": "https://...", // Available when status is "completed"
    "progress": 85, // Processing progress (0-100)
    "estimatedTime": 60 // Estimated seconds remaining
  }
}

Status Values

  • pending: Image is queued for processing
  • processing: Image is being generated
  • completed: Image is ready and available for download
  • failed: Generation failed (check error message)

Upload Image

Upload an image for image-to-image generation.

Endpoint

POST /upload-image-image

Request

Use multipart/form-data to upload image file.

curl -X POST https://gempix2ai.site/api/upload-image-image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg"

Response

{
  "code": 0,
  "msg": "Upload successful",
  "data": {
    "imageUrl": "https://...",
    "imageKey": "r2-key-123"
  }
}

Supported Formats

  • JPEG/JPG
  • PNG
  • WebP
  • Maximum file size: 50MB

Error Codes

| Code - Description | |------|-------------| | 0 - Success | | 1000 - Invalid parameters | | 1001 - Insufficient credits | | 1002 - Authentication failed | | 1003 - Rate limit exceeded | | 5000 - Server error |

Error Response Example

{
  "code": 1001,
  "msg": "Insufficient credits",
  "data": {
    "required": 2,
    "current": 0
  }
}

Rate Limits

  • Free tier: 10 requests/hour
  • Starter: 100 requests/hour
  • Pro: 500 requests/hour
  • community: Custom limits

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1697472000

SDKs & Libraries

We provide official SDKs for popular programming languages:

  • JavaScript/TypeScript: npm install @gempix2-friendly/sdk
  • Python: pip install gempix2-friendly
  • Go: go get github.com/gempix2-friendly/go-sdk

JavaScript Example

import { Veo3o1 } from '@gempix2-friendly/sdk';

const client = new Veo3o1('YOUR_API_KEY');

const images = await client.generateImage({
  generationType: 'text_to_image',
  prompt: 'A beautiful sunset over the ocean',
  aspectRatio: '16:9'
});

console.log('images UUID:', images.uuid);

Webhooks

Configure webhooks to receive notifications when images are completed.

Setup

  1. Go to API Settings
  2. Enter your webhook URL
  3. Select events to receive

Event Types

  • images.completed: Image generation completed successfully
  • images.failed: Image generation failed

Webhook Payload

{
  "event": "images.completed",
  "uuid": "images-uuid-123",
  "imageUrl": "https://...",
  "timestamp": "2025-10-16T10:05:00Z"
}

Best Practices

  1. Poll responsibly: Check images status every 5-10 seconds, not continuously
  2. Handle errors: Implement retry logic with exponential backoff
  3. Cache results: Store generated images to avoid regenerating
  4. Use webhooks: More efficient than polling for completion
  5. Validate inputs: Check prompt length and image formats before API calls

Support

Need help with the API?