Text-to-Image API Reference

Text-to-Image: generate an image from a text prompt

curl --request POST \
  --url https://api.apiyi.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "gpt-image-2-all",
  "prompt": "Landscape 16:9 cinematic, old lighthouse at sunset"
}
'

import requests

url = "https://api.apiyi.com/v1/images/generations"

payload = {
    "model": "gpt-image-2-all",
    "prompt": "Landscape 16:9 cinematic, old lighthouse at sunset"
}
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({
    model: 'gpt-image-2-all',
    prompt: 'Landscape 16:9 cinematic, old lighthouse at sunset'
  })
};

fetch('https://api.apiyi.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.apiyi.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([
    'model' => 'gpt-image-2-all',
    'prompt' => 'Landscape 16:9 cinematic, old lighthouse at sunset'
  ]),
  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.apiyi.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"model\": \"gpt-image-2-all\",\n  \"prompt\": \"Landscape 16:9 cinematic, old lighthouse at sunset\"\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.apiyi.com/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"gpt-image-2-all\",\n  \"prompt\": \"Landscape 16:9 cinematic, old lighthouse at sunset\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apiyi.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  \"model\": \"gpt-image-2-all\",\n  \"prompt\": \"Landscape 16:9 cinematic, old lighthouse at sunset\"\n}"

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

{
  "data": [
    {
      "b64_json": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "created": 1778037127,
  "usage": {
    "input_tokens": 98,
    "output_tokens": 1185,
    "total_tokens": 1283
  }
}

POST

images

generations

Text-to-Image: generate an image from a text prompt

curl --request POST \
  --url https://api.apiyi.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "gpt-image-2-all",
  "prompt": "Landscape 16:9 cinematic, old lighthouse at sunset"
}
'

import requests

url = "https://api.apiyi.com/v1/images/generations"

payload = {
    "model": "gpt-image-2-all",
    "prompt": "Landscape 16:9 cinematic, old lighthouse at sunset"
}
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({
    model: 'gpt-image-2-all',
    prompt: 'Landscape 16:9 cinematic, old lighthouse at sunset'
  })
};

fetch('https://api.apiyi.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.apiyi.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([
    'model' => 'gpt-image-2-all',
    'prompt' => 'Landscape 16:9 cinematic, old lighthouse at sunset'
  ]),
  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.apiyi.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"model\": \"gpt-image-2-all\",\n  \"prompt\": \"Landscape 16:9 cinematic, old lighthouse at sunset\"\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.apiyi.com/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"gpt-image-2-all\",\n  \"prompt\": \"Landscape 16:9 cinematic, old lighthouse at sunset\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apiyi.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  \"model\": \"gpt-image-2-all\",\n  \"prompt\": \"Landscape 16:9 cinematic, old lighthouse at sunset\"\n}"

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

{
  "data": [
    {
      "b64_json": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "created": 1778037127,
  "usage": {
    "input_tokens": 98,
    "output_tokens": 1185,
    "total_tokens": 1283
  }
}

The interactive Playground on the right supports direct online testing. Enter your API Key in the Authorization field (format: Bearer sk-xxx), type a prompt, and click send.

Scope: This page is for text-to-image generation. Just enter a prompt — no image upload required. To edit or fuse existing images, use the Image Editing endpoint.

🖥️ Browser Playground limitation (default b64_json mode)This endpoint defaults to response_format: "b64_json", so the response carries a multi-MB base64 string and the browser Playground may show 请求时发生错误: unable to complete request — the request actually succeeded; the browser just can’t render such a long base64 string.Recommended workflow:

Just want to view the image in the Playground? Pass "response_format": "url" explicitly — the response is a single R2 link and renders fine.
Want base64? Copy the code sample below and run it locally — the code will decode and save the image to a file automatically.

All image APIs are synchronous — there is no task ID to poll, and if your client disconnects the result is lost while the request is still billed. Set a generous timeout for this model; see Image API Essentials & Best Practices.

⚠️ Parameter Support

size: the field has no effect — sending auto or any concrete value does not error, but the value is silently ignored by the server. Dimensions are driven entirely by the prompt:
- Prompt mentions a size/ratio (e.g., “Landscape 16:9”) → the model follows the prompt
- Prompt has no size hints → the same prompt yields varied dimensions across calls, like “drawing different cards” — useful for exploring multiple compositions
- For strict size locking, use gpt-image-2-vip (supports auto + 30 explicit sizes)
n / quality / aspect_ratio: ❌ rejected. Sending these may trigger parameter validation errors.

Write size and ratio directly into the prompt, e.g.:

Landscape 16:9 cinematic, old lighthouse by the sea at dusk
Portrait 9:16 phone wallpaper, cyberpunk city rainy night
1024×1024 square logo, minimalist cat line art

Put size descriptions at the front of the prompt for better adherence.

Code Examples

Python

import requests

API_KEY = "sk-your-api-key"

response = requests.post(
    "https://api.apiyi.com/v1/images/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "gpt-image-2-all",
        "prompt": "Landscape 16:9 cinematic, old lighthouse at sunset, photorealistic",
        "response_format": "url"
    },
    timeout=300  # conservative — absorbs tail latency + image download time
).json()

image_url = response["data"][0]["url"]
print(image_url)

b64_json mode (returns base64 image data):

import base64
import requests

response = requests.post(
    "https://api.apiyi.com/v1/images/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "gpt-image-2-all",
        "prompt": "1024x1024 square logo, minimalist cat line art",
        "response_format": "b64_json"
    },
    timeout=300  # conservative — absorbs tail latency + image download time
).json()

# Verified 2026-07: b64_json is raw base64 (no data: prefix); earlier versions included the prefix — a check is safest
b64 = response["data"][0]["b64_json"]
if b64.startswith("data:"):
    b64 = b64.split(",", 1)[1]
with open("output.png", "wb") as f:
    f.write(base64.b64decode(b64))

cURL

curl -X POST "https://api.apiyi.com/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-all",
    "prompt": "Landscape 16:9 cinematic, old lighthouse at sunset",
    "response_format": "url"
  }'

Node.js

const API_KEY = "sk-your-api-key";

const response = await fetch(
  "https://api.apiyi.com/v1/images/generations",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "gpt-image-2-all",
      prompt: "1024x1024 square logo, minimalist cat line art",
      response_format: "b64_json"
    })
  }
);

const data = await response.json();
// Verified raw base64 (no data: prefix) — prepend before rendering; earlier versions included the prefix, so check first
let b64 = data.data[0].b64_json;
if (!b64.startsWith("data:")) b64 = `data:image/png;base64,${b64}`;
document.getElementById("result").src = b64;

Browser JavaScript (Fetch)

const resp = await fetch('https://api.apiyi.com/v1/images/generations', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer sk-your-api-key'
    },
    body: JSON.stringify({
        model: 'gpt-image-2-all',
        prompt: 'Portrait 9:16 phone wallpaper, cyberpunk city rainy night',
        response_format: 'b64_json'
    })
});
const { data } = await resp.json();
let b64 = data[0].b64_json;
if (!b64.startsWith('data:')) b64 = `data:image/png;base64,${b64}`;
document.getElementById('result').src = b64;

Parameters Quick Reference

Parameter	Type	Required	Description
`model`	string	Yes	Fixed value: `gpt-image-2-all`
`prompt`	string	Yes	Prompt. Include size/ratio/style here
`size`	string	No	Only `auto` is accepted (the same prompt yields varied dimensions). For strict size locking, use `gpt-image-2-vip`
`response_format`	string	No	`b64_json` (default, raw base64) or `url` (returns R2 CDN link); always pass explicitly

Detailed parameter constraints and allowed values are shown in the right-hand Playground. The response_format field supports dropdown selection.

Response Format

data[0] returns either url or b64_json — never both (depends on response_format). This endpoint defaults to b64_json. b64_json mode (default):

{
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "created": 1778037127,
  "usage": {
    "input_tokens": 98,
    "output_tokens": 1185,
    "total_tokens": 1283
  }
}

url mode (requires explicit "response_format": "url", R2 CDN globally accelerated):

{
  "data": [
    {
      "url": "https://r2cdn.copilotbase.com/r2cdn2/0e82148a-bec0-4b42-bbca-117c6b42581b.png"
    }
  ],
  "created": 1778037331,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 2074,
    "total_tokens": 2104
  }
}

Compatibility note: verified July 2026 — the b64_json field is raw base64 without the data: prefix; decode it to write a file, or prepend the prefix yourself before rendering. Earlier versions did include the prefix, so always run a startsWith('data:') check first to handle both shapes.

Authorizations

Authorization

string

header

required

API Key from the API易 Console

Body

application/json

model

enum<string>

default:gpt-image-2-all

required

Model name, fixed to gpt-image-2-all

Available options:

gpt-image-2-all

prompt

string

required

Prompt. Include size/ratio/style here, e.g., Landscape 16:9 cinematic, old lighthouse at sunset

Example:

"Landscape 16:9 cinematic, old lighthouse at sunset"

response_format

enum<string>

default:b64_json

Response format. b64_json returns a base64 string already prefixed with a data URL header (default); url returns an R2 CDN link

Available options:

b64_json,

url

Response

Image successfully generated. Defaults to base64 in data[0].b64_json — url is not returned in the same response.

Image generation response. data[0] returns either url or b64_json, never both (depends on response_format; this endpoint defaults to b64_json).

data

object[]

Result array (this model returns 1 image per call)

Show child attributes

created

integer

Unix timestamp (seconds)

usage

object

Token usage statistics

Show child attributes

GPT-Image-2-All Overview Image Editing API Reference

Basics

Basic API

Image API (Official)

Video API (Official)

Multimodal Understanding API

Text API

Code Examples

Python

cURL

Node.js

Browser JavaScript (Fetch)

Parameters Quick Reference

Response Format

Authorizations

Body

Response

​Code Examples

​Python

​cURL

​Node.js

​Browser JavaScript (Fetch)

​Parameters Quick Reference

​Response Format

Authorizations

Body

Response

Code Examples

Python

cURL

Node.js

Browser JavaScript (Fetch)

Parameters Quick Reference

Response Format