👷Using the API

Train custom models and generate images using the dreamlook.ai API

View an interactive version of our API spec here: https://api.dreamlook.ai/redoc

Start a mode training job

By default, trained checkpoints are automatically deleted after 48h. You can subscribe to a Plan to increase this duration: https://dreamlook.ai/pricing

We will explain step by step how to train a Stable Diffusion model using the API.

  1. Sign up or log in on dreamlook.ai

  2. Generate an API key on dreamlook.ai/api-keys. Treat this key like a password: keep it safe, and don't expose it publicly!

  3. Export your API key as the environment variable DREAMLOOK_API_KEY :

export DREAMLOOK_API_KEY="dl-YOURKEYHERE"

  1. Go to https://dreamlook.ai/dreambooth and switch "Expert mode" on:

You can now configure your run:

  1. Copy the content of "API request" and paste it into a terminal. Running the command will trigger a training job:

You will get a unique job ID as a response:

{
    "job_id":"db_63d83f95"
}

Jobs created from the API are also visible from the website, so you can check https://dreamlook.ai/jobs/dreambooth to see how your job is progressing.

Dry runs

During development, you may want to perform tests without actually being charged tokens. You can use the dry run mode for this purpose.

In your request payload to /dreambooth, add the field "dry_run": true to start a job in dry run mode. Here's an example:

curl 'https://api.dreamlook.ai/dreambooth' \
  -H "content-type: application/json" \
  -H "authorization: Bearer $DREAMLOOK_API_KEY" \
  --data-raw '{
    "steps": 1200,
    "learning_rate": 0.000001,
    "instance_prompt": "photo of ukj person",
    "base_model": "stable-diffusion-v1-5",
    "saved_model_format":"original",
    "saved_model_weights_format": "safetensors",
    "dry_run": true,
    "image_urls": [
        "https://images.unsplash.com/photo-1593439960697-140200051c2c",
        "https://images.unsplash.com/photo-1593440012688-b6ede71180c3",
        "https://images.unsplash.com/photo-1593440497401-b87d3bb3fb8b",
        "https://images.unsplash.com/photo-1593202764227-040c0c69f3d9",
        "https://images.unsplash.com/photo-1593202620896-f7cb529ed581",
        "https://images.unsplash.com/photo-1593202873672-79aeb34143d8",
        "https://images.unsplash.com/photo-1593202695230-db2abb34a742"
    ]
}'

Response:

{
    "job_id": "TEST_50d2285d"
}

As you can see, a dummy job ID is returned, prefixed with "TEST_". This is not a real job: the job ID is not tracked, and you won't see it in your job list either from the API or from the website.

If you have specified a callback (see below), the callback will be sent along with some dummy data (including sample checkpoints, generated images, thumbnails, etc.).

Dry runs also work on our image_gen and dreambooth_image_gen endpoints.

Callbacks: Receive notifications when your jobs are done

You may want to add a callback to your request. Typically, this is a publicly accessible URL that points to your own backend and triggers further processing on your end after your job finishes. When the run has finished, the job payload (including results) will be sent via a POST request to this URL.

The payload corresponds to the job object, as returned by the /jobs/{job_type}/{job_id} endpoint.

How to test callbacks

  1. Head over to dreamlook.ai/dreambooth

  2. Set up the run parameters and upload your images

  3. Enter your publicly accessible URL into the field "Callback URL"

  4. Click the button "Test it". This will send a POST request with a test payload to your endpoint. The test payload contains a signed URL that points to a untrained Stable Diffusion 1.5 model (regardless of your parameters).

You won't be charged for this action. The resulting job ID is a test ID ("TEST_") that is not tracked.

Keeping track of your jobs

Reading the state of a single job

During or after training, you can retrieve the status and results for an individual job using the /jobs/{job_type}/{job_id} endpoint. job_type can be one of dreambooth, image_gen, or dreambooth_image_gen.

Here's an example with a Dreambooth job with ID db_1ccb410f:

curl \
  -H "content-type: application/json" \
  -H "authorization: Bearer $DREAMLOOK_API_KEY" \
  https://api.dreamlook.ai/jobs/dreambooth/db_1ccb410f

Response:

{
    "job_type": "dreambooth",
    "job_id": "db_1ccb410f",
    "state": "success",
    "state_updated": "2023-06-05T14:01:16.279400",
    "state_running_start": "2023-06-05T13:59:46.960858",
    "state_running_end": "2023-06-05T14:01:16.279400",
    "state_queued_start": "2023-06-05T13:59:38.121577",
    "state_queued_end": "2023-06-05T13:59:46.960858",
    "queued_duration": 8.839281,
    "running_duration": 89.318542,
    "queueing_state": "default",
    "config": {
        "image_urls": [
            "gs://nyxai-galactus-prd.appspot.com/dreambooth/4DNzz1vuLIa7gdaNwPDkJL1Onv73/2023-6-5-9-59_11zmplck7u/images/21a498e6_kxq8tsip_photo_2023-05-26-22-03-50.jpeg",
            "gs://nyxai-galactus-prd.appspot.com/dreambooth/4DNzz1vuLIa7gdaNwPDkJL1Onv73/2023-6-5-9-59_11zmplck7u/images/4723de21_115rofqb_photo_2023-05-26-22-03-49.jpeg",
            "gs://nyxai-galactus-prd.appspot.com/dreambooth/4DNzz1vuLIa7gdaNwPDkJL1Onv73/2023-6-5-9-59_11zmplck7u/images/c5529bdc_z8lm9jlk_photo_2023-05-26-22-03-46.jpeg",
            "gs://nyxai-galactus-prd.appspot.com/dreambooth/4DNzz1vuLIa7gdaNwPDkJL1Onv73/2023-6-5-9-59_11zmplck7u/images/d8cc970b_zxwng9gd_photo_2023-05-26-22-03-42.jpeg",
            "gs://nyxai-galactus-prd.appspot.com/dreambooth/4DNzz1vuLIa7gdaNwPDkJL1Onv73/2023-6-5-9-59_11zmplck7u/images/e60013d5_d0g5zh0d_photo_2023-05-26-22-03-44.jpeg",
            "gs://nyxai-galactus-prd.appspot.com/dreambooth/4DNzz1vuLIa7gdaNwPDkJL1Onv73/2023-6-5-9-59_11zmplck7u/images/f3277b89_xwgmpaxv_photo_2023-05-26-22-03-47.jpeg"
        ],
        "instance_prompt": "photo of ukj person",
        "steps": 100,
        "saved_model_format": "original",
        "saved_model_weights_format": "safetensors",
        "base_model": "stable-diffusion-v1-5",
        "checkpoint_id": null,
        "crop_method": "center",
        "learning_rate": 1e-06,
        "learning_rate_te": 1e-06,
        "learning_rate_te1": null,
        "learning_rate_te2": null,
        "enable_offset_noise": false,
        "callback": null,
        "extract_lora": "original",
        "captions_file_url": null,
        "save_checkpoints_at": null,
        "text_encoder_training": null,
        "checkpoint_availability_mode": "standard",
        "priority": 100
    },
    "dreambooth_result": {
        "checkpoints": [
            {
                "checkpoint_id": "ckp_12ed2b03",
                "url": "https://storage.googleapis.com/nyxai-standard-usc2/models/db_1ccb410f/dreamlookai_stable-diffusion-v1-5_step_100_db_1ccb410f_ckp_12ed2b03.safetensors?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=174139095815-compute%40developer.gserviceaccount.com%2F20230605%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20230605T140116Z&X-Goog-Expires=172800&X-Goog-SignedHeaders=host&X-Goog-Signature=916d6d912be0e369e979d0866d093ce7d7a907002984984b6276eb4202a10d82b59360682749ca31718e2686b70802693a5bc50fd2271d54008aa252d2fd796b0a007944cec24523f474218aadcec12d1917083929b871dce930c6d37e5caf57dd04989af2cb017fc78962f41711adf1a3ab24546ed82d001bfef3341c5440179470d8a8268c4d79784419a6063ec47ddf482bf187e4467cace6533bfc5fc96ee67de91698b7963f28dce38cb38ac9b551030ed49ba10727fbadfec33e9d17421ba555472029e305069fb4def91f0523e8bedd6d44d824a5eb87b8d74da459f10fb9292f5ee936687e8546e2f0a883388c2ab65ef72f2ef6ac7d13aaedccefea",
                "is_extracted_lora": false,
                "model_type": "sd-v1",
                "checkpoint_type": "checkpoint",
                "training_step": 100,
                "size_bytes": 2132625438,
                "file_format": "safetensors",
                "availability_mode": "standard",
                "is_available": true
            },
            {
                "checkpoint_id": "ckp_dc155e79",
                "url": "https://storage.googleapis.com/nyxai-standard-usc2/models/db_1ccb410f/dreamlookai_stable-diffusion-v1-5_lora_step_100_db_1ccb410f_ckp_dc155e79.safetensors?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=174139095815-compute%40developer.gserviceaccount.com%2F20230605%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20230605T140116Z&X-Goog-Expires=172800&X-Goog-SignedHeaders=host&X-Goog-Signature=2fc29caa6cb82fb26803f869221eebd6508a525292efebd1d1fbeac9417af6ce39dcec696e54fe4dddcaad5eadc4d50ed2944c8119991056b8b31fe139812b69a40951ed3470d0e0c729a83e6314a97e522c068e0905901b4ccda5eefd3d8a0389ed51b6a9186e99d18987345be95f51382f3d9ddda17f462221cc048c23f45280213c51438abc85ed7a4fa1945d25fc7f69ce31ea4c3709c0a04786f3ce0b295ee2fd0a7b4dca35a4b07a9289393b5b64fab073977bd8a0f3da21936e47d712477cf2e07f63e4e7ee7ee41f4ef1f195bafa6d91fd5016fff6dc2d8cf302621c2bba312a6f9bb52386807755e0d4c2d8ce4de2c198b347d68058cb882ce47a73",
                "is_extracted_lora": true,
                "checkpoint_type": "lora",
                "model_type": "sd-v1",
                "training_step": 100,
                "size_bytes": 75611048,
                "file_format": "safetensors",
                "availability_mode": "standard",
                "is_available": true
            }
        ],
        "sanitized_images": []
    },
    "image_gen_results": null,
    "percentage_done": 100,
    "failure_reason": null,
    "failure_reason_data": null,
    "thumbnails": null,
    "tags": []
}

The job object looks similar for all job types:

  • state: Can one of queued, running, success, failure

  • config: Contains the configuration the job was started with

  • dreambooth_result: Any results from model training

    • checkpoints: List of checkpoints associated with this run. Checkpoints can be full checkpoints or LoRA checkpoints (checkpoint_type="lora") . Also note the training_step for each checkpoint.

  • image_gen_results: Any results from image generation (only for image-gen or dreambooth-image-gen jobs)

List all your jobs

In order to list all existing jobs, use the endpoint /jobs/{job_type} (e.g. /jobs/dreambooth). By default this lists the most recent 50 jobs.

Error codes

HTTP response codeMeaning

307

Temporary redirect. You may be using an outdated endpoint that is now deprecated.

404

The endpoint or resource does not exist.

401

Unauthorized. You need to provide a valid API key.

403

Forbidden. This may happen if you don't have enough quota (tokens) to fulfill the request.

422

Your job configuration/payload is invalid or not allowed.

5xx

Error codes of 500 or higher indicate that there is something wrong on our side. Please try again or reach out to us.

PreviousUsing the websiteNextGenerate images

Last updated