Images API - Nbility AI Gateway

Generate images from text or edit an existing image using the endpoints below.

Generate images

Overview

Use the image generation endpoint to create images from a text prompt.

POST /v1/images/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Supported models

Model	Description
`gpt-image-2`	GPT Image 2 (image, image-4k group exclusive)
`gpt-image-2-1k`	GPT Image 2 1K (image-stable group exclusive)
`gpt-image-2-2k`	GPT Image 2 2K (image-stable group exclusive)
`gpt-image-2-4k`	GPT Image 2 4K (image-stable group exclusive)

The longest edge must not exceed 3,840 pixels. Each edge must be a multiple of 16 pixels, the aspect ratio must not exceed 3:1, and the total pixel count must be between 655,360 and 8,294,400.

Response format and image count

response_format: "url" returns hosted image URLs in data[].url.

response_format: "b64_json" returns base64 image data in data[].b64_json.

When an upstream provider returns base64 data or a data:image/...;base64,... URL internally, the gateway normalizes the client response according to response_format.

Base64 image results may still be cached internally for logs and downloads, but the client response remains b64_json when response_format is set to b64_json.

The n parameter is accepted for OpenAI-compatible requests, but the actual number of returned images depends on the upstream provider. For gpt-image-2 compatible channels, requests commonly return one image even when n is greater than 1.

Header parameters

Request examples

cURL

curl https://api.nbility.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-New-Api-Async-Task: true" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A panda riding a bicycle with a backpack that says I love China",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

Python

import requests

response = requests.post(
    "https://api.nbility.ai/v1/images/generations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
        "X-New-Api-Async-Task": "true",
    },
    json={
        "model": "gpt-image-2",
        "prompt": "A panda riding a bicycle with a backpack that says I love China",
        "n": 1,
        "size": "1024x1024",
        "response_format": "url",
    },
)
print(response.json())

Node.js

const response = await fetch('https://api.nbility.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'X-New-Api-Async-Task': 'true',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A panda riding a bicycle with a backpack that says I love China',
    n: 1,
    size: '1024x1024',
    response_format: 'url',
  }),
});

console.log(await response.json());

Go

package main

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

func main() {
	body := []byte(`{
		"model":"gpt-image-2",
		"prompt":"A panda riding a bicycle with a backpack that says I love China",
		"n":1,
		"size":"1024x1024",
		"response_format":"url"
	}`)

	req, _ := http.NewRequest("POST", "https://api.nbility.ai/v1/images/generations", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-New-Api-Async-Task", "true")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(string(data))
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        var body = """
            {
              \"model\": \"gpt-image-2\",
              \"prompt\": \"A panda riding a bicycle with a backpack that says I love China\",
              \"n\": 1,
              \"size\": \"1024x1024\",
              \"response_format\": \"url\"
            }
            """;

        var client = HttpClient.newHttpClient();
        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.nbility.ai/v1/images/generations"))
            .header("Authorization", "Bearer YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .header("X-New-Api-Async-Task", "true")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Async response example

When X-New-Api-Async-Task: true is set, the API returns task information:

{
  "code": "success",
  "message": "success",
  "data": {
    "task_id": "task_xxx",
    "status": "submitted"
  }
}

Async task query

Use GET /v1/images/tasks/:task_id to query an async image generation or image edit task created with X-New-Api-Async-Task: true.

GET /v1/images/tasks/{task_id}
Authorization: Bearer YOUR_API_KEY

cURL

curl https://api.nbility.ai/v1/images/tasks/task_xxx \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import requests

response = requests.get(
    "https://api.nbility.ai/v1/images/tasks/task_xxx",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())

Node.js

const response = await fetch('https://api.nbility.ai/v1/images/tasks/task_xxx', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
  },
});

console.log(await response.json());

The response includes task status and, after completion, image result fields such as image_urls and result_url when available.

{
  "code": "success",
  "message": "success",
  "data": {
    "task_id": "task_xxx",
    "status": "succeeded",
    "status_raw": "SUCCESS",
    "action": "generations",
    "progress": "100%",
    "submit_time": 1745711800,
    "start_time": 1745711802,
    "finish_time": 1745711868,
    "result_url": "https://domain.com/cdn/20250427/uj1ojiZ9c1tR4PPbeV5Ts0pEu357py.png",
    "image_urls": [
      "https://domain.com/cdn/20250427/uj1ojiZ9c1tR4PPbeV5Ts0pEu357py.png"
    ]
  }
}

Response example

{
  "created": 1745711868,
  "data": [
    {
      "revised_prompt": "A panda riding a bicycle with a backpack that says I love China",
      "url": "https://domain.com/cdn/20250427/uj1ojiZ9c1tR4PPbeV5Ts0pEu357py.png"
    }
  ]
}

Edit images

Overview

Use the image editing endpoint with a source image, an optional mask, and a prompt.

POST /v1/images/edits
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

Supported models

Model	Description
`gpt-image-2`	GPT Image 2 (image, image-4k group exclusive)
`gpt-image-2-1k`	GPT Image 2 1K (image-stable group exclusive)
`gpt-image-2-2k`	GPT Image 2 2K (image-stable group exclusive)
`gpt-image-2-4k`	GPT Image 2 4K (image-stable group exclusive)

Request parameters

The longest edge must not exceed 3,840 pixels. Each edge must be a multiple of 16 pixels, the aspect ratio must not exceed 3:1, and the total pixel count must be between 655,360 and 8,294,400.

Request examples

cURL

curl https://api.nbility.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F 'model="gpt-image-2"' \
  -F 'image=@"input.png"' \
  -F 'prompt="Merge the two images naturally into one composition"' \
  -F 'n="1"' \
  -F 'size="1024x1024"' \
  -F 'response_format="url"'

Python

import requests

with open("input.png", "rb") as image_file:
    response = requests.post(
        "https://api.nbility.ai/v1/images/edits",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        data={
            "model": "gpt-image-2",
            "prompt": "Merge the two images naturally into one composition",
            "n": "1",
            "size": "1024x1024",
            "response_format": "url",
        },
        files={"image": image_file},
    )
print(response.json())

Node.js

import fs from 'node:fs';
import FormData from 'form-data';

const form = new FormData();
form.append('model', 'gpt-image-2');
form.append('image', fs.createReadStream('input.png'));
form.append('prompt', 'Merge the two images naturally into one composition');
form.append('n', '1');
form.append('size', '1024x1024');
form.append('response_format', 'url');

const response = await fetch('https://api.nbility.ai/v1/images/edits', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    ...form.getHeaders(),
  },
  body: form,
});

console.log(await response.json());

Go

package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	var buf bytes.Buffer
	w := multipart.NewWriter(&buf)
	w.WriteField("model", "gpt-image-2")
	w.WriteField("prompt", "Merge the two images naturally into one composition")
	w.WriteField("n", "1")
	w.WriteField("size", "1024x1024")
	w.WriteField("response_format", "url")

	fw, _ := w.CreateFormFile("image", "input.png")
	f, _ := os.Open("input.png")
	io.Copy(fw, f)
	f.Close()
	w.Close()

	req, _ := http.NewRequest("POST", "https://api.nbility.ai/v1/images/edits", &buf)
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Content-Type", w.FormDataContentType())
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(string(data))
}

Response example

{
  "created": 1589478378,
  "data": [
    {
      "url": "https://domain.com/cdn/20250427/uj1ojiZ9c1tR4PPbeV5Ts0pEu357py.png"
    }
  ]
}