LucyDream API: Image Generation Documentation

Overview

The LucyDream API allows you to generate images using custom models created via the model creation endpoint (see the model creation API documentation for details). Provide a prompt and reference a previously created model to generate high-quality images.

Base URL: https://my.lucydream.ai/wp-json/

Endpoint: POST /apiservices/v1/generate

Authentication: Include your API key in the X-API-Key header. Obtain your key from the API dashboard after approval as an API user. If you don’t have access, log in to the website and apply via the API registration page.

Rate Limits and Quotas: Subject to server limits and your account balance.

Important Notes:

• Do NOT include a tune object in the request body; this triggers image generation instead of model creation.
• Use a model previously created with your account (reference via tune_id and safetensors_path).
• Image generation is processed asynchronously but typically returns quickly with the generated image URLs.
• The api_mode defaults to ‘spicy’ if not specified.

Request

Method: POST

Headers

Content-Type: application/json

X-API-Key: <your_api_key>

Body Parameters (JSON)

The body must be a JSON object with the following required parameters:

Parameter	Type	Required	Description
prompt	string	Yes	The text prompt describing the image to generate.
tune_id	string	Yes	The unique ID of the custom model (from model creation response).
safetensors_path	string	Yes	The URL to the model’s .safetensors file (e.g., from your configured R2 bucket).
trigger_name	string	Yes	Must be "man" or "woman" to match the model’s trigger behavior.
api_mode	string	Yes	The API mode ("spicy" or "xxx").

Example Request Body:

{
"prompt": "A beautiful blonde in lingerie at sunset",
"tune_id": "12345",
"safetensors_path": "your-bucket-url/12345.safetensors",
"trigger_name": "woman",
"api_mode": "spicy"
}

Response

Success (200 OK)

A JSON object with the generated image details.

Field	Type	Description
image_url	string	URL of the full generated image.
thumbnail_url	string	URL of the thumbnail image.
user_prompt	string	The original prompt used.
w	integer	Width of the image (default: 896).
h	integer	Height of the image (default: 1152).
balance	number	Updated account balance after generation (if applicable).
message	string	Success message or additional info.

Example Success Response:

{
"image_url": "https://my.lucydream.ai/generated/image.jpg",
"thumbnail_url": "https://my.lucydream.ai/generated/thumbnail.jpg",
"user_prompt": "A beautiful blonde in lingerie at sunset",
"w": 896,
"h": 1152,
"balance": 3.8,
"message": "Image generated successfully"
}

Errors

Errors return a JSON object with an error field.

400 Bad Request: Missing or invalid parameters.

{

“error”: “The trigger_name parameter must be either ‘woman’ or ‘man’.”

}

403 Forbidden: Invalid or missing API key

{

“error”: “Invalid API key”

}

500 Internal Server Error: Issues with generation or service availability.

{

“error”: “Failed to generate image”

}

Examples

cURL

curl -X POST https://my.lucydream.ai/wp-json/apiservices/v1/generate \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key_here" \
-d '{
"prompt": "A beautiful blonde in lingerie at sunset",
"tune_id": "12345",
"safetensors_path": "https://your-bucket-url/12345.safetensors",
"trigger_name": "woman",
"api_mode": "spicy"
}'

JavaScript (Fetch)

fetch('https://my.lucydream.ai/wp-json/apiservices/v1/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    prompt: 'A beautiful blonde in lingerie at sunset',
    tune_id: '12345',
    safetensors_path: 'https://your-bucket-url/12345.safetensors',
    trigger_name: 'woman',
    api_mode: 'standard'
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Additional Information

• Model Requirements: Ensure the tune_id and safetensors_path reference a valid model created under your account.
• Model Creation: Be sure to check the full model creation documentation.

If you need help or have any questions, let us know!