> For the complete documentation index, see [llms.txt](https://deepmode.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://deepmode.gitbook.io/docs/api-endpoints/handling-images/generate-image.md).

# Generate Image

This operation costs **1 credit.** 

#### Endpoint

```
POST /api/images/generate
```

<table><thead><tr><th width="204">Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>model_id</code></td><td>string</td><td>Yes</td><td>Unique identifier of the model.</td></tr><tr><td><code>prompt</code></td><td>string</td><td>Yes</td><td>Prompt to use.</td></tr><tr><td><code>negative_prompt</code></td><td>string</td><td>No</td><td>Negative Prompt to use.</td></tr><tr><td><code>num_images</code></td><td>integer</td><td>No</td><td>Number of images to generate. Range: 1-8. Default: 1.</td></tr><tr><td><code>upscale</code></td><td>boolean</td><td>No</td><td>X4 super-resolution. Default: false.</td></tr><tr><td><code>ratio</code></td><td>string</td><td>No</td><td>Possible values: <code>portrait</code>, <code>square</code>. Default: <code>portrait</code>.</td></tr><tr><td><code>callback</code></td><td>string</td><td>No</td><td>A URL that will be called when the prompt is done processing. If not provided, the endpoint will run in <strong>sync mode</strong> and return the response when the image generation is complete.</td></tr></tbody></table>

#### Callback

The `callback` parameter allows you to specify a URL that will be called when the image generation is complete. This is useful for asynchronous processing, where you want to receive a notification when the image is ready.

The `callback` URL should be a valid URL that can receive a POST request from the API. This URL will be called by the API when the image generation is complete, and it will receive the generated image(s) as a JSON payload.

Here are some options for the `callback` URL:

1. **Your own server**: You can set up a server to receive the callback request. You'll need to create an endpoint that can receive the POST request and process the generated image(s).
2. **Webhook service**: You can use a webhook service like Zapier, Integromat, or Webhook.io to receive the callback request.&#x20;
3. **Cloud function**: for example, AWS Lambda, Google Cloud Functions, Azure Functions, or any other cloud function that can receive the callback request.

#### Sync mode

If the `callback` parameter is not provided, the endpoint will run in **sync mode**. In this mode, the API will generate the image and return the response when the generation is complete.&#x20;

#### Request Example

```bash
curl -X POST "https://api.deepmode.ai/api/images/generate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_API_KEY" \
-d '{
  "model_id": "b8a9f7e5d1c3a2f91e3d5",
  "prompt": "A beautiful landscape with mountains and a river.",
  "negative_prompt": "rainy, foggy",
  "num_images": 3,
  "upscale": true,
  "ratio": "square",
  "callback": "https://api.my_ai_startup.com/image-generator/callback/1234567890abcdef"
}'
```

#### Response

Upon successful generation, the API returns the following response:

<pre class="language-json"><code class="lang-json"><strong>// Response for request in async mode (i.e. callback provided)
</strong>{"message": "Generating images..."}
<strong>
</strong><strong>// Response for request in sync mode &#x26; for callback in async mode
</strong><strong>{
</strong>  "images":
  [
    {
      "id": "93b5e1c7a4f2d6g8h9k1m",
      "file_name": "120e453f-3a73-4016-ad6a-5cd5e00ddd45.jpeg",
      "model_id": "b8a9f7e5d1c3a2f91e3d5",
      "image_url": "https://deepmodeimage.blob.core.windows.net/deepmode-user-image/120e453f-3a73-4016-ad6a-5cd5e00ddd45.jpeg?st=2024-04-29T14%3A28%3A02Z&#x26;se=2024-04-29T15%3A28%3A02Z&#x26;sp=r&#x26;sv=2023-11-03&#x26;sr=b&#x26;sig=NaLrBA8mqrBMiFL1e9gCbuQAvgEMmG39D6iyHkbuy2E%3D",
      "prompt": "A beautiful landscape with mountains and a river.",
      "negative_prompt": "rainy, foggy",
      "upscaled": true,
      "ratio": "portrait"
    },
    {    
      "id": "f7e5d1c3a2f91e3d5c6b8",
      "file_name": "b6084a21f6e-9421-49c2-8f4d-51b2c3d4e5f6.jpeg",
      "model_id": "b8a9f7e5d1c3a2f91e3d5",
      "image_url": "https://deepmodeimage.blob.core.windows.net/deepmode-user-image/b6084a21f6e-9421-49c2-8f4d-51b2c3d4e5f6.jpeg?st=2024-04-29T14%3A28%3A02Z&#x26;se=2024-04-29T15%3A28%3A02Z&#x26;sp=r&#x26;sv=2023-11-03&#x26;sr=b&#x26;sig=NaLrBA8mqrBMiFL1e9gCbuQAvgEMmG39D6iyHkbuy2E%3D",
      "prompt": "A beautiful landscape with mountains and a river.",
      "negative_prompt": "rainy, foggy",
      "upscaled": true,
      "ratio": "portrait"
    },
    {
      "id": "c6b8a9f7e5d1c3a2f91e3",
      "file_name": "2f6d914a-5b83-46c1-9f3e-721a4b8c9d1e.jpeg",
      "model_id": "b8a9f7e5d1c3a2f91e3d5",
      "image_url": "https://deepmodeimage.blob.core.windows.net/deepmode-user-image/2f6d914a-5b83-46c1-9f3e-721a4b8c9d1e.jpeg?st=2024-04-29T14%3A28%3A02Z&#x26;se=2024-04-29T15%3A28%3A02Z&#x26;sp=r&#x26;sv=2023-11-03&#x26;sr=b&#x26;sig=NaLrBA8mqrBMiFL1e9gCbuQAvgEMmG39D6iyHkbuy2E%3D",
      "prompt": "A beautiful landscape with mountains and a river.",
      "negative_prompt": "rainy, foggy",
      "upscaled": true,
      "ratio": "portrait"
    }
  ]
}
</code></pre>