Create image generation

curl --request POST \
  --url https://api-direct.dimilinks.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "model": "gpt-image-2",
  "n": 1,
  "size": "1:1",
  "output_format": "png",
  "output_compression": 123,
  "background": "auto",
  "moderation": "auto",
  "wait_for_result": true,
  "image_urls": "<string>",
  "mask_url": "<string>",
  "response_format": "b64_json",
  "user": "<string>"
}
'

import requests

url = "https://api-direct.dimilinks.com/v1/images/generations"

payload = {
    "prompt": "<string>",
    "model": "gpt-image-2",
    "n": 1,
    "size": "1:1",
    "output_format": "png",
    "output_compression": 123,
    "background": "auto",
    "moderation": "auto",
    "wait_for_result": True,
    "image_urls": "<string>",
    "mask_url": "<string>",
    "response_format": "b64_json",
    "user": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    model: 'gpt-image-2',
    n: 1,
    size: '1:1',
    output_format: 'png',
    output_compression: 123,
    background: 'auto',
    moderation: 'auto',
    wait_for_result: true,
    image_urls: '<string>',
    mask_url: '<string>',
    response_format: 'b64_json',
    user: '<string>'
  })
};

fetch('https://api-direct.dimilinks.com/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-direct.dimilinks.com/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'model' => 'gpt-image-2',
    'n' => 1,
    'size' => '1:1',
    'output_format' => 'png',
    'output_compression' => 123,
    'background' => 'auto',
    'moderation' => 'auto',
    'wait_for_result' => true,
    'image_urls' => '<string>',
    'mask_url' => '<string>',
    'response_format' => 'b64_json',
    'user' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api-direct.dimilinks.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"model\": \"gpt-image-2\",\n  \"n\": 1,\n  \"size\": \"1:1\",\n  \"output_format\": \"png\",\n  \"output_compression\": 123,\n  \"background\": \"auto\",\n  \"moderation\": \"auto\",\n  \"wait_for_result\": true,\n  \"image_urls\": \"<string>\",\n  \"mask_url\": \"<string>\",\n  \"response_format\": \"b64_json\",\n  \"user\": \"<string>\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-direct.dimilinks.com/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"model\": \"gpt-image-2\",\n  \"n\": 1,\n  \"size\": \"1:1\",\n  \"output_format\": \"png\",\n  \"output_compression\": 123,\n  \"background\": \"auto\",\n  \"moderation\": \"auto\",\n  \"wait_for_result\": true,\n  \"image_urls\": \"<string>\",\n  \"mask_url\": \"<string>\",\n  \"response_format\": \"b64_json\",\n  \"user\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-direct.dimilinks.com/v1/images/generations")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"model\": \"gpt-image-2\",\n  \"n\": 1,\n  \"size\": \"1:1\",\n  \"output_format\": \"png\",\n  \"output_compression\": 123,\n  \"background\": \"auto\",\n  \"moderation\": \"auto\",\n  \"wait_for_result\": true,\n  \"image_urls\": \"<string>\",\n  \"mask_url\": \"<string>\",\n  \"response_format\": \"b64_json\",\n  \"user\": \"<string>\"\n}"

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

{
  "task_id": "task_xxx",
  "data": [],
  "created": 1777080000
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "code": "<string>"
  }
}

POST

images

generations

Create image generation

curl --request POST \
  --url https://api-direct.dimilinks.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "model": "gpt-image-2",
  "n": 1,
  "size": "1:1",
  "output_format": "png",
  "output_compression": 123,
  "background": "auto",
  "moderation": "auto",
  "wait_for_result": true,
  "image_urls": "<string>",
  "mask_url": "<string>",
  "response_format": "b64_json",
  "user": "<string>"
}
'

import requests

url = "https://api-direct.dimilinks.com/v1/images/generations"

payload = {
    "prompt": "<string>",
    "model": "gpt-image-2",
    "n": 1,
    "size": "1:1",
    "output_format": "png",
    "output_compression": 123,
    "background": "auto",
    "moderation": "auto",
    "wait_for_result": True,
    "image_urls": "<string>",
    "mask_url": "<string>",
    "response_format": "b64_json",
    "user": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    model: 'gpt-image-2',
    n: 1,
    size: '1:1',
    output_format: 'png',
    output_compression: 123,
    background: 'auto',
    moderation: 'auto',
    wait_for_result: true,
    image_urls: '<string>',
    mask_url: '<string>',
    response_format: 'b64_json',
    user: '<string>'
  })
};

fetch('https://api-direct.dimilinks.com/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-direct.dimilinks.com/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'model' => 'gpt-image-2',
    'n' => 1,
    'size' => '1:1',
    'output_format' => 'png',
    'output_compression' => 123,
    'background' => 'auto',
    'moderation' => 'auto',
    'wait_for_result' => true,
    'image_urls' => '<string>',
    'mask_url' => '<string>',
    'response_format' => 'b64_json',
    'user' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api-direct.dimilinks.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"model\": \"gpt-image-2\",\n  \"n\": 1,\n  \"size\": \"1:1\",\n  \"output_format\": \"png\",\n  \"output_compression\": 123,\n  \"background\": \"auto\",\n  \"moderation\": \"auto\",\n  \"wait_for_result\": true,\n  \"image_urls\": \"<string>\",\n  \"mask_url\": \"<string>\",\n  \"response_format\": \"b64_json\",\n  \"user\": \"<string>\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-direct.dimilinks.com/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"model\": \"gpt-image-2\",\n  \"n\": 1,\n  \"size\": \"1:1\",\n  \"output_format\": \"png\",\n  \"output_compression\": 123,\n  \"background\": \"auto\",\n  \"moderation\": \"auto\",\n  \"wait_for_result\": true,\n  \"image_urls\": \"<string>\",\n  \"mask_url\": \"<string>\",\n  \"response_format\": \"b64_json\",\n  \"user\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-direct.dimilinks.com/v1/images/generations")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"model\": \"gpt-image-2\",\n  \"n\": 1,\n  \"size\": \"1:1\",\n  \"output_format\": \"png\",\n  \"output_compression\": 123,\n  \"background\": \"auto\",\n  \"moderation\": \"auto\",\n  \"wait_for_result\": true,\n  \"image_urls\": \"<string>\",\n  \"mask_url\": \"<string>\",\n  \"response_format\": \"b64_json\",\n  \"user\": \"<string>\"\n}"

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

{
  "task_id": "task_xxx",
  "data": [],
  "created": 1777080000
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "code": "<string>"
  }
}

gpt-image-2 is the DimiLinks image generation model. It supports text-to-image and image-to-image workflows, with up to nine reference images supplied through image_urls.

We recommend adding ?async=true. Synchronous mode waits for image generation to finish before returning and is more likely to be interrupted by a gateway or client timeout.

Request URL

POST https://api-direct.dimilinks.com/v1/images/generations?async=true
Content-Type: application/json
Authorization: Bearer <DIMILINKS_API_KEY>

Text-to-image example

curl "https://api-direct.dimilinks.com/v1/images/generations?async=true" \
  -H "Authorization: Bearer $DIMILINKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cyberpunk poster of a cat, neon lighting, cinematic atmosphere",
    "n": 1,
    "size": "16:9",
    "resolution": "2k",
    "output_format": "png"
  }'

Image-to-image example

curl "https://api-direct.dimilinks.com/v1/images/generations?async=true" \
  -H "Authorization: Bearer $DIMILINKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Keep the person consistent and restyle the image as a cinematic beach portrait at sunset",
    "n": 1,
    "size": "16:9",
    "resolution": "4k",
    "image_urls": [
      "https://example.com/reference.png"
    ]
  }'

Asynchronous response

{
  "created": 1777080000,
  "task_id": "task_xxx",
  "data": []
}

After receiving task_id, call Retrieve image task to retrieve the result.

Synchronous response

Synchronous mode returns after the image is ready:

{
  "created": 1777080000,
  "task_id": "task_xxx",
  "data": [
    {
      "url": "https://lmage2.dimilinks.com/p/img/img_xxx/0?exp=1777166400000&sig=...",
      "file_id": "file_xxx"
    }
  ]
}

Result fields

data[].url is an image result URL. Handle it as follows:

/p/img/...: a relative path. Prefix it with https://lmage2.dimilinks.com before displaying or downloading it. The path requires no Bearer token because the URL includes a signature and expiration time.
https://lmage2.dimilinks.com/p/img/...: a complete image URL that can be requested or displayed directly.

For asynchronous tasks, image results are in data.data[] on the task response, not result.data[]. The img_xxx in an image URL is an image-pool resource ID; it is different from the public task ID returned by submission.

Parameters

Parameter	Type	Default	Description
`model`	string	`gpt-image-2`	Model name.
`prompt`	string	Required	Generation or editing prompt.
`n`	integer	`1`	Number of images generated per request. The `1k` tier is fixed at `1`; `2k` and `4k` support up to `4`.
`size`	string	`1024x1024`	Aspect ratio such as `1:1` or `16:9`, or exact `WxH` pixels such as `3840x2160`.
`resolution`	string	Empty	Resolution tier: `1k` / `2k` / `4k`.
`output_format`	string	Empty	Output format: `png` / `jpeg` / `webp`.
`output_compression`	integer	Empty	Output compression quality for `jpeg` or `webp`.
`background`	string	Empty	Background preference: `auto` / `transparent` / `opaque`.
`moderation`	string	Empty	Content moderation level: `auto` / `low`.
`user`	string	Empty	Caller-side user identifier for auditing.
`wait_for_result`	boolean	`true`	Set to `false` for asynchronous submission.
`image_urls`	string \| array \| object	Empty	JSON reference-image field, with up to nine images.
`mask_url`	string	Empty	Inpainting mask; requires at least one reference image.
`response_format`	string	Empty	Set to `b64_json` to return base64 directly; not recommended as the default.

Enable asynchronous mode

Any one of the following enables asynchronous mode:

Query parameter: ?async=true
Query parameter: ?wait_for_result=false
Request header: Prefer: respond-async
Request body: "wait_for_result": false

Reference-image format

We recommend image_urls:

{
  "image_urls": [
    "https://example.com/ref.png",
    "data:image/png;base64,iVBORw0KGgo..."
  ]
}

The API also accepts reference_images, images, image, image_url, input_image, and input_images.

Reference-image limits

A request can include up to nine reference images.
Each reference image can be up to 20 MB.
HTTP(S) URLs, Data URLs, and raw base64 are supported.
Browser blob: URLs cannot be submitted directly. Upload the image to your server or convert it to a Data URL first.

Differences between resolution tiers

Tier	Maximum `n` per request	Typical time	Description
`1k`	1	About 60 seconds	Entry tier for previews or low-cost batch generation.
`2k`	4	About 120 seconds	Recommended tier for most production image generation.
`4k`	4	About 180 seconds	High-fidelity tier that also supports some extreme aspect ratios such as `21:9`.

See the Pricing page in the console for current prices. Each resolution tier is priced independently.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

async

boolean

Set to true to submit an async image task.

wait_for_result

boolean

Set to false to submit an async image task.

Body

application/json

prompt

string

required

model

string

default:gpt-image-2

integer

default:1

1k resolution allows n=1 only; 2k and 4k allow up to 4.

Required range: 1 <= x <= 4

size

string

Examples:

"1:1"

"16:9"

"3840x2160"

resolution

enum<string>

Available options:

1k,

2k,

4k

output_format

string

Examples:

"png"

"jpeg"

"webp"

output_compression

integer

background

string

Examples:

"auto"

"transparent"

"opaque"

moderation

string

Examples:

"auto"

"low"

wait_for_result

boolean

image_urls

mask_url

string

response_format

string

Example:

"b64_json"

user

string

Response

Image generation result or async submission

Option 1
Option 2

task_id

string

required

Example:

"task_xxx"

data

object[]

required

Show child attributes

Example:

[]

created

integer

Example:

1777080000

Basics

Chat

Images / gpt-image-2

Images / more models

Videos / unified video API

Video / grok-imagine-video

IDE and CLI integrations

Create image generation

Request URL

Text-to-image example

Image-to-image example

Asynchronous response

Synchronous response

Result fields

Parameters

Enable asynchronous mode

Reference-image format

Reference-image limits

Differences between resolution tiers

Authorizations

Query Parameters

Body

Response

​Request URL

​Text-to-image example

​Image-to-image example

​Asynchronous response

​Synchronous response

​Result fields

​Parameters

​Enable asynchronous mode

​Reference-image format

​Reference-image limits

​Differences between resolution tiers

Authorizations

Query Parameters

Body

Response

Request URL

Text-to-image example

Image-to-image example

Asynchronous response

Synchronous response

Result fields

Parameters

Enable asynchronous mode

Reference-image format

Reference-image limits

Differences between resolution tiers