API Reference

OpenAI-compatible API for image generation, audio generation, model management, authentication, and gallery operations

Authentication

All API endpoints accept an API key via the Authorization header:

Authorization: Bearer YOUR_API_KEY

Some endpoints require additional authentication for admin operations. See Authentication for details.

Image Generation

Endpoint: POST /v1/chat/completions

The chat completions endpoint accepts messages with image generation requests.

Request Format

{
  "model": "sdxl",
  "messages": [
    {"role": "user", "content": "A serene mountain landscape at sunset"}
  ],
  "samConfig": {
    "steps": 30,
    "guidance_scale": 7.5,
    "width": 1024,
    "height": 1024,
    "negative_prompt": "low quality, blurry",
    "seed": 12345,
    "scheduler": "dpm++_sde_karras"
  }
}

Response Format

Returns JSON with image URLs in the choices array.

Generation Defaults

Endpoint: GET /v1/generation/defaults

Returns the default generation parameters for the configured models.

Models API

List Models

Endpoint: GET /v1/models

Returns a list of all available image and audio models.

List Cached Models

Endpoint: GET /v1/models/cached

Returns models currently loaded in GPU memory.

Model Info

Endpoint: GET /v1/models/{model_id}/info

Returns detailed information about a specific model.

Evict Model

Endpoint: POST /v1/models/{model_id}/evict

Evicts a model from GPU cache to free memory.

Refresh Models

Endpoint: POST /v1/models/refresh

Rescans the model directory and updates the model list.

List LoRAs

Endpoint: GET /v1/loras

Returns all LoRA adapters available.

List Audio Models

Endpoint: GET /v1/models/audio

Returns all installed audio generation models.

Model Search and Download

Search CivitAI

Endpoint: POST /v1/models/search/civitai

Search for models on CivitAI.

Search HuggingFace

Endpoint: POST /v1/models/search/huggingface

Search for models on HuggingFace.

Download from CivitAI

Endpoint: POST /v1/models/download/civitai

Download a model from CivitAI.

Download from HuggingFace

Endpoint: POST /v1/models/download/huggingface

Download a model from HuggingFace.

Download Audio Model

Endpoint: POST /v1/models/download/audio

Download an audio generation model.

Download from URL

Endpoint: POST /v1/models/download/url

Download a model from any URL.

Download Status

Endpoint: GET /v1/models/download/status

Returns status of all download tasks.

Endpoint: GET /v1/models/download/status/{task_id}

Returns status of a specific download task.

Cancel Delete

Endpoint: DELETE /v1/models/download/{task_id}

Cancel an active download.

Model Cache

Endpoint: GET /v1/models/cache/status

Returns cache status and configuration.

Audio Generation

List Audio Models

Endpoint: GET /v1/audio/models

Returns all available audio generation models.

Generate Audio

Endpoint: POST /v1/audio/generations

Generate audio from a text prompt (stable audio, music generation).

Audio Statistics

Endpoint: GET /v1/audio/stats

Returns audio generation statistics.

Get Audio File

Endpoint: GET /v1/audio/{filename}

Retrieves a generated audio file.

Delete Audio Model

Endpoint: DELETE /v1/models/audio/{model_id}

Remove an audio model from disk.

Gallery API

List Gallery

Endpoint: GET /v1/gallery

Returns all images in the gallery.

List Audio Gallery

Endpoint: GET /v1/gallery/audio

Returns all audio generations in the gallery.

Gallery Config

Endpoint: GET /v1/gallery/config

Returns gallery configuration settings.

Gallery Stats

Endpoint: GET /v1/gallery/stats

Returns gallery statistics.

Gallery Tags

Endpoint: GET /v1/gallery/tags

Returns all tags used in the gallery.

Cleanup Gallery

Endpoint: POST /v1/gallery/cleanup

Clean up temporary files and thumbnails.

Delete Gallery Image

Endpoint: DELETE /v1/gallery/{image_id}

Delete an image from the gallery.

Delete Gallery Audio

Endpoint: DELETE /v1/gallery/audio/{audio_id}

Delete an audio entry from the gallery.

Update Image Privacy

Endpoint: PATCH /v1/gallery/{image_id}/privacy

Update the privacy setting of a gallery image.

Update Image Tags

Endpoint: PATCH /v1/gallery/{image_id}/tags

Update tags on a gallery image.

Authentication API

Generate API Key

Endpoint: POST /v1/auth/keys/generate

Generate a new API key.

List API Keys

Endpoint: GET /v1/auth/keys

Returns all API keys.

Delete API Key

Endpoint: DELETE /v1/auth/keys/{key_id}

Delete an API key.

Revoke API Key

Endpoint: POST /v1/auth/keys/{key_id}/revoke

Revoke an API key (marks as revoked but keeps record).

Create Session

Endpoint: POST /v1/auth/sessions

Create a web authentication session.

List Sessions

Endpoint: GET /v1/auth/sessions

Returns all active sessions.

Delete Session

Endpoint: DELETE /v1/auth/sessions/{session_id}

Delete a session.

Get Current User

Endpoint: GET /v1/auth/me

Returns information about the current authenticated user.

Authentication Stats

Endpoint: GET /v1/auth/stats

Returns authentication statistics.

Bootstrap Registration

Endpoint: POST /v1/auth/bootstrap

Bootstrap the first admin user on a fresh installation.

Registration Mode

Endpoint: GET /v1/auth/registration-mode

Check if registration mode is enabled.

Register User

Endpoint: POST /v1/auth/register

Register a new user (requires registration mode).

Invitations

Endpoints:

  • POST /v1/auth/invites - Create an invitation
  • GET /v1/auth/invites - List invitations
  • DELETE /v1/auth/invites/{code} - Delete an invitation

Pending Registrations

Endpoints:

  • GET /v1/auth/pending - List pending registrations
  • POST /v1/auth/pending/{reg_id}/approve - Approve a pending registration
  • POST /v1/auth/pending/{reg_id}/reject - Reject a pending registration
  • DELETE /v1/auth/pending/{reg_id} - Delete a pending registration

Admin API

Get Config

Endpoint: GET /v1/admin/config

Returns the current server configuration (admin only).

Update Config

Endpoint: PUT /v1/admin/config

Update server configuration (admin only).

Sync Model Cache

Endpoint: POST /v1/admin/cache/sync

Sync model cache between filesystem and database (admin only).

Restart Server

Endpoint: POST /v1/admin/restart

Restart the ALICE server (admin only).

Update API

Update Status

Endpoint: GET /v1/update/status

Returns current update status.

Check for Updates

Endpoint: POST /v1/update/check

Check for available updates.

Apply Update

Endpoint: POST /v1/update/apply

Apply a pending update.

Rollback Update

Endpoint: POST /v1/update/rollback

Rollback to a previous version.

List Backups

Endpoint: GET /v1/update/backups

Returns available backups.

Image Serving

Endpoint: GET /images/{filename}

Serves generated images by filename.

SAM Config Parameters

All fields are optional - server uses defaults if omitted.

Field Type Description
steps int (1-150) Inference steps
guidance_scale float (0.0-20.0) CFG scale
width int (64-2048) Image width
height int (64-2048) Image height
negative_prompt string Negative prompt
seed int Random seed
scheduler string Scheduler name

Valid Schedulers

  • euler, euler_ancestral
  • dpm++_sde_karras (default), dpm++_2m_karras
  • ddim, pndm, lms, heun

Next Steps