Imagine Endpoints

Endpoints

The Imagine service provides endpoints for image generation, service monitoring, and web interface access.

Service Information

GET /

Returns service health status and information.

Response

{
  "status": "healthy",
  "env": "production",
  "ui": "https://imagine.genstack.app/ui"
}

Status Codes

200 - Service is healthy
500 - Internal server error

Image Generation

POST /

Generates an image using Stable Diffusion XL Lightning.

Request

Content-Type: application/json

{
  "prompt": "A beautiful sunset over mountains",
  "genstackToken": "user_auth_token",
  "developerId": "dev_123", // Optional
  "applicationId": "app_456",
  "negativePrompt": "blur, haze", // Optional
  "seed": 12345, // Optional
  "steps": 20, // Optional
  "width": 1024, // Optional
  "height": 1024, // Optional
  "overrideGrossMarginPercent": 50 // Optional
}

Parameters:

Name	Type	Required	Description
prompt	string	Yes	The main prompt for image generation
genstackToken	string	Yes	Valid Genstack authentication token
developerId	string	No	Developer’s unique identifier
applicationId	string	No	Application’s unique identifier
negativePrompt	string	No	Things to avoid in the generation
seed	number	No	Seed for reproducible generation
steps	number	No	Number of generation steps
width	number	No	Output image width
height	number	No	Output image height
overrideGrossMarginPercent	number	No	Custom gross margin percentage (0-99)

Response

{
  "imageUrl": "data:image/png;base64,...",
  "prompt": "A beautiful sunset over mountains",
  "model": "sdxl-lightning",
  "metadata": {
    "seed": 12345,
    "steps": 20,
    "width": 1024,
    "height": 1024,
    "negativePrompt": "blur, haze"
  },
  "usage": {
    "type": "imagine",
    "cost": "0.01"
  },
  "balanceBefore": "1000",
  "balanceAfter": "900"
}

Web Interface

GET /ui

Provides a web-based interface for image generation.

Response

Returns an HTML page with the image generation interface.

Error Responses

All error responses follow this format:

{
  "error": {
    "type": "ErrorType",
    "message": "Description of what went wrong",
    "details": {
      // Additional error context
    }
  }
}

Common error types include:

InvalidRequest
InsufficientFunds
InvalidCredentials
InternalError