> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.ideogram.ai/v1/api-reference/edit-images/remix-v3/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.ideogram.ai/_mcp/server.

# Remix with Ideogram 3.0

POST https://api.ideogram.ai/v1/ideogram-v3/remix
Content-Type: multipart/form-data

Remix provided images synchronously based on a given prompt and optional parameters with the Ideogram 3.0 model.

Input images are cropped to the chosen aspect ratio before being remixed.

Supported image formats include JPEG, PNG, and WebP.

Images links are available for a limited period of time; if you would like to keep the image, you must download it.


Reference: https://developer.ideogram.ai/v1/api-reference/edit-images/remix-v3

## Authentication

- `Api-Key` header (required) — API key for access control. Use in the header with the name \"Api-Key\"

## Request

### Body (multipart/form-data)

This endpoint expects a multipart form with multiple files.

- `image` (file, required) — The image to remix binary (max size 25MB); only JPEG, WebP and PNG formats are supported at this time.
- `prompt` (string, required) — The prompt to use to generate the image.
- `image_weight` (integer, optional)
- `seed` (integer, optional)
- `resolution` (enum, optional)
- `aspect_ratio` (enum, optional)
- `rendering_speed` (enum, optional)
- `magic_prompt` (enum, optional)
- `negative_prompt` (string, optional) — Description of what to exclude from an image. Descriptions in the prompt take precedence to descriptions in the negative prompt.
- `num_images` (integer, optional) — Number of images to generate.
- `color_palette` (ColorPaletteWithPresetNameOrMembers, optional)
- `style_codes` (list of string, optional)
- `style_type` (enum, optional)
- `style_preset` (enum, optional)
- `style_reference_images` (files, optional) — A set of images to use as style references (max size 25MB per image; the whole request must stay under 50MB). The images should be in JPEG, PNG or WebP format.
- `character_reference_images` (files, optional) — Generations with character reference are subject to the character reference pricing. A set of images to use as character references (max size 25MB per image; the whole request must stay under 50MB), currently only supports 1 character reference image. The images should be in JPEG, PNG or WebP format.
- `character_reference_images_mask` (files, optional) — Optional masks for character reference images. When provided, must match the number of character_reference_images. Each mask should be a grayscale image of the same dimensions as the corresponding character reference image. The images should be in JPEG, PNG or WebP format.

## Response

### 200

Image(s) generated successfully.

- `created` (datetime, required) — The time the request was created.
- `data` (list of ImageGenerationObjectV3, required) — A list of ImageObjects that contain the generated image(s).

## Errors

### 400 Bad Request Error

Invalid input provided.

- `any`

### 403 Forbidden Error

Not authorized to generate an image.

- `any`

### 422 Unprocessable Entity Error

Prompt or provided image failed safety check.

- `error` (string, required)

### 429 Too Many Requests Error

Too many requests.

- `any`

## Types

### ImageGenerationObjectV3

- `prompt` (string, required) — The prompt used for the generation. This may be different from the original prompt.
- `resolution` (enum, required) — The resolutions supported for Ideogram 3.0.
  - Allowed values: `512x1536`, `576x1408`, `576x1472`, `576x1536`, `640x1344`, `640x1408`, `640x1472`, `640x1536`, `704x1152`, `704x1216`, `704x1280`, `704x1344`, `704x1408`, `704x1472`, `736x1312`, `768x1088`, `768x1216`, `768x1280`, `768x1344`, `800x1280`, `832x960`, `832x1024`, `832x1088`, `832x1152`, `832x1216`, `832x1248`, `864x1152`, `896x960`, `896x1024`, `896x1088`, `896x1120`, `896x1152`, `960x832`, `960x896`, `960x1024`, `960x1088`, `1024x832`, `1024x896`, `1024x960`, `1024x1024`, `1088x768`, `1088x832`, `1088x896`, `1088x960`, `1120x896`, `1152x704`, `1152x832`, `1152x864`, `1152x896`, `1216x704`, `1216x768`, `1216x832`, `1248x832`, `1280x704`, `1280x768`, `1280x800`, `1312x736`, `1344x640`, `1344x704`, `1344x768`, `1408x576`, `1408x640`, `1408x704`, `1472x576`, `1472x640`, `1472x704`, `1536x512`, `1536x576`, `1536x640`
- `is_image_safe` (boolean, required) — Whether this request passes safety checks. If false, the url field will be empty.
- `seed` (integer, required) — Random seed. Set for reproducible generation.
- `url` (string, optional, nullable) — The direct link to the image generated.
- `upscaled_resolution` (string, optional) — Output resolution, only used if operations alters image dimensions, such as upscale, crop etc.
- `style_type` (enum, optional, default: GENERAL) — The style type to generate with.
  - Allowed values: `AUTO`, `GENERAL`, `REALISTIC`, `DESIGN`, `FICTION`

## Examples

**Request**

```json
{
  "aspect_ratio": "1x2",
  "character_reference_images": [],
  "character_reference_images_mask": [],
  "image": "<file: <file1>>",
  "image_weight": 50,
  "prompt": "A photo of a cat",
  "rendering_speed": "DEFAULT",
  "style_reference_images": [],
  "style_type": "AUTO"
}
```

**Response**

```json
{
  "created": {},
  "data": [
    {
      "prompt": "A photo of a cat",
      "resolution": "1280x800",
      "is_image_safe": true,
      "seed": 12345,
      "url": "https://ideogram.ai/api/images/ephemeral/xtdZiqPwRxqY1Y7NExFmzB.png?exp=1743867804&sig=e13e12677633f646d8531a153d20e2d3698dca9ee7661ee5ba4f3b64e7ec3f89",
      "style_type": "GENERAL"
    }
  ]
}
```

**SDK Code**

```python
import requests

response = requests.post(
  "https://api.ideogram.ai/v1/ideogram-v3/remix",
  headers={
    "Api-Key": "<apiKey>"
  },
  data={
    "prompt": "A photo of a cat",
    "rendering_speed": "TURBO"
  },
  files={
    "image": open("<file1>", "rb"),
  }
)
print(response.json())
with open('output.png', 'wb') as f:
  f.write(requests.get(response.json()['data'][0]['url']).content)

```

```typescript
const formData = new FormData();
formData.append('prompt', 'A photo of a cat');
formData.append('rendering_speed', 'TURBO');
formData.append('image', '<file1>');
const response = await fetch('https://api.ideogram.ai/v1/ideogram-v3/remix', {
  method: 'POST',
  headers: { 'Api-Key': '<apiKey>' },
  body: formData
});
const data = await response.json();
console.log(data);

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ideogram.ai/v1/ideogram-v3/remix"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n1x2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"color_palette\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image_weight\"\r\n\r\n50\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"magic_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"negative_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nA photo of a cat\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"rendering_speed\"\r\n\r\nDEFAULT\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_codes\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_preset\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_type\"\r\n\r\nAUTO\r\n-----011000010111000001101001--\r\n")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Api-Key", "<apiKey>")
	req.Header.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.ideogram.ai/v1/ideogram-v3/remix")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Api-Key"] = '<apiKey>'
request["Content-Type"] = 'multipart/form-data; boundary=---011000010111000001101001'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n1x2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"color_palette\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image_weight\"\r\n\r\n50\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"magic_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"negative_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nA photo of a cat\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"rendering_speed\"\r\n\r\nDEFAULT\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_codes\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_preset\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_type\"\r\n\r\nAUTO\r\n-----011000010111000001101001--\r\n"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.ideogram.ai/v1/ideogram-v3/remix")
  .header("Api-Key", "<apiKey>")
  .header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n1x2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"color_palette\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image_weight\"\r\n\r\n50\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"magic_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"negative_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nA photo of a cat\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"rendering_speed\"\r\n\r\nDEFAULT\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_codes\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_preset\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_type\"\r\n\r\nAUTO\r\n-----011000010111000001101001--\r\n")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.ideogram.ai/v1/ideogram-v3/remix', [
  'multipart' => [
    [
        'name' => 'aspect_ratio',
        'contents' => '1x2'
    ],
    [
        'name' => 'image',
        'filename' => '<file1>',
        'contents' => null
    ],
    [
        'name' => 'image_weight',
        'contents' => '50'
    ],
    [
        'name' => 'prompt',
        'contents' => 'A photo of a cat'
    ],
    [
        'name' => 'rendering_speed',
        'contents' => 'DEFAULT'
    ],
    [
        'name' => 'style_type',
        'contents' => 'AUTO'
    ]
  ]
  'headers' => [
    'Api-Key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.ideogram.ai/v1/ideogram-v3/remix");
var request = new RestRequest(Method.POST);
request.AddHeader("Api-Key", "<apiKey>");
request.AddParameter("multipart/form-data; boundary=---011000010111000001101001", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n1x2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"color_palette\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image_weight\"\r\n\r\n50\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"magic_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"negative_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nA photo of a cat\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"rendering_speed\"\r\n\r\nDEFAULT\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_codes\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_preset\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_type\"\r\n\r\nAUTO\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Api-Key": "<apiKey>",
  "Content-Type": "multipart/form-data; boundary=---011000010111000001101001"
]
let parameters = [
  [
    "name": "aspect_ratio",
    "value": "1x2"
  ],
  [
    "name": "color_palette",
    "value": 
  ],
  [
    "name": "image",
    "fileName": "<file1>"
  ],
  [
    "name": "image_weight",
    "value": "50"
  ],
  [
    "name": "magic_prompt",
    "value": 
  ],
  [
    "name": "negative_prompt",
    "value": 
  ],
  [
    "name": "num_images",
    "value": 
  ],
  [
    "name": "prompt",
    "value": "A photo of a cat"
  ],
  [
    "name": "rendering_speed",
    "value": "DEFAULT"
  ],
  [
    "name": "resolution",
    "value": 
  ],
  [
    "name": "seed",
    "value": 
  ],
  [
    "name": "style_codes",
    "value": 
  ],
  [
    "name": "style_preset",
    "value": 
  ],
  [
    "name": "style_type",
    "value": "AUTO"
  ]
]

let boundary = "---011000010111000001101001"

var body = ""
var error: NSError? = nil
for param in parameters {
  let paramName = param["name"]!
  body += "--\(boundary)\r\n"
  body += "Content-Disposition:form-data; name=\"\(paramName)\""
  if let filename = param["fileName"] {
    let contentType = param["content-type"]!
    let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
    if (error != nil) {
      print(error as Any)
    }
    body += "; filename=\"\(filename)\"\r\n"
    body += "Content-Type: \(contentType)\r\n\r\n"
    body += fileContent
  } else if let paramValue = param["value"] {
    body += "\r\n\r\n\(paramValue)"
  }
}

let request = NSMutableURLRequest(url: NSURL(string: "https://api.ideogram.ai/v1/ideogram-v3/remix")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```