LucyDream API: Model Creation

Overview

The LucyDream API allows you to create custom models for image generation. These models are trained using a set of images you provide and can later be used in image generation requests (see the image generation API documentation for details).

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:

• Include a tune object in the request body to trigger model creation. Without it, the request is treated as image generation. (see API image generation documentation).
• The created model will be stored in the Cloudflare R2 bucket you configure in your API dashboard (required for storage).
• Model creation is asynchronous; you will receive an initiation response, and the model will be available once processing completes.
• Use the returned tune_id to reference the model in future requests.

Request

Method: POST

Headers

Content-Type: application/json

X-API-Key: <your_api_key>

Body Parameters (JSON)

The body must include a tune object with the following parameters:

Parameter	Type	Required	Description
tune	object	Yes	Defines the model parameters.
tune.title	string	Yes	Model title (max 15 characters).
tune.name	string	Yes	Must be “man” or “woman” to define the model’s trigger behavior.
tune.image_urls	array	Yes	Exactly 5 publicly accessible URLs to images (JPEG, PNG, or WEBP format) for training the model.
Other parameters	varies	No	No additional parameters required.

Example Request Body:

{
  "tune": {
    "title": "Test-Model",
    "name": "woman",
    "image_urls": [
      "https://example.com/images/1.jpg",
      "https://example.com/images/2.jpg",
      "https://example.com/images/3.jpg",
      "https://example.com/images/4.jpg",
      "https://example.com/images/5.jpg"
    ]
  }
}

Response

Success (200 OK)

A JSON object confirming initiation of model creation. The model file (in .safetensors format) will be stored in your configured bucket upon completion.

Field	Type	Description
success	boolean	true if initiation succeeded.
tune_id	string	Unique ID for the model (use this to track or reference the model).
message	string	Confirmation message.

Example Success Response:

{
  "success": true,
  "tune_id": "12345",
  "message": "Model creation initiated successfully"
}

Once complete, the model’s .safetensors file will be available at a URL like https://your-bucket-url/.safetensors in your configured storage bucket.

Errors

Errors return a JSON object with an error field.

400 Bad Request: Invalid or missing parameters.

{
"error": "The tune.image_urls parameter must contain exactly 5 URLs."
}

403 Forbidden: Invalid or missing API key.

{
"error": "Invalid API key"
}

500 Internal Server Error: Issues with image fetching or service availability.

{
"error": "Failed to fetch image 1"
}

Storage Configuration

Before creating models, configure your Cloudflare R2 storage in the API dashboard. Provide:

• Bucket URL (e.g., https://pub-12345678910.r2.dev)
• Bucket Name
• R2 Account ID
• R2 Access Key ID
• R2 Secret Key

Examples

cURL Example

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 '{
    "tune": {
      "title": "Test-Model",
      "name": "woman",
      "image_urls": [
        "https://example.com/images/1.jpg",
        "https://example.com/images/2.jpg",
        "https://example.com/images/3.jpg",
        "https://example.com/images/4.jpg",
        "https://example.com/images/5.jpg"
      ]
    }
  }'

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({
    tune: {
      title: 'Test-Model',
      name: 'woman',
      image_urls: [
        'https://example.com/images/1.jpg',
        'https://example.com/images/2.jpg',
        'https://example.com/images/3.jpg',
        'https://example.com/images/4.jpg',
        'https://example.com/images/5.jpg'
      ]
    }
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Additional Information

• Image Requirements: Ensure the 5 images are publicly accessible and in supported formats. They should represent the same subject for optimal model training.
• Model Usage: After creation, use the tune_id and stored .safetensors URL in image generation requests.
• Image Generation: Be sure to check the full image generation documentation.

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