# Using the API

{% hint style="info" %}
View the full API documentation here: <https://api.dreamlook.ai/redoc>
{% endhint %}

## Start a mode training job

{% hint style="warning" %}
**By default, trained checkpoints are automatically deleted after 48h.**\
You can subscribe to a Plan to increase this duration: <https://dreamlook.ai/pricing>
{% endhint %}

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](https://dreamlook.ai/)
2. Generate an API key on [dreamlook.ai/api-keys](https://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` :

```sh
export DREAMLOOK_API_KEY="dl-YOURKEYHERE"
```

4. Go to <https://dreamlook.ai/dreambooth> and switch "Expert mode" on:

<div data-full-width="true"><figure><img src="https://3775798052-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbjzMS9bi5lfz4h6oo4EA%2Fuploads%2FpFP5LL7qTayAM7cBhmOa%2FScreenshot%202023-06-29%20at%2020.57.47.png?alt=media&#x26;token=031d3353-578a-4d07-b1a4-59b010b31268" alt=""><figcaption></figcaption></figure></div>

You can now configure your run:

<div data-full-width="true"><figure><img src="https://3775798052-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbjzMS9bi5lfz4h6oo4EA%2Fuploads%2FcZhbkorsF10DIORi77rV%2FScreenshot%202023-06-29%20at%2020.57.54.png?alt=media&#x26;token=68e40935-acc6-4484-a1f7-cad2f1d54e45" alt=""><figcaption></figcaption></figure></div>

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

<div data-full-width="true"><figure><img src="https://3775798052-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbjzMS9bi5lfz4h6oo4EA%2Fuploads%2F7lMPut784MsHQlEFmzsp%2FScreenshot%202023-06-29%20at%2020.49.06.png?alt=media&#x26;token=50d73ea0-171d-4e03-a75d-fb741ec2352f" alt=""><figcaption></figcaption></figure></div>

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:

```bash
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:

```json
{
    "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](https://dreamlook.ai/dreambooth-api)
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`:

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

Response:

```json
{
    "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 be 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

<table><thead><tr><th width="211">HTTP response code</th><th>Meaning</th></tr></thead><tbody><tr><td>307</td><td>Temporary redirect. You may be using an outdated endpoint that is now deprecated.</td></tr><tr><td>404</td><td>The endpoint or resource does not exist.</td></tr><tr><td>401</td><td>Unauthorized. You need to provide a valid API key.</td></tr><tr><td>403</td><td>Forbidden. This may happen if you don't have enough quota (tokens) to fulfill the request.</td></tr><tr><td>422</td><td>Your job configuration/payload is invalid or not allowed.</td></tr><tr><td>5xx</td><td>Error codes of 500 or higher indicate that there is something wrong on our side. Please try again or reach out to us.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dreamlook.ai/train-models/using-the-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.