# 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>


---

# 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://deepmode.gitbook.io/docs/api-endpoints/handling-images/generate-image.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.