Chat API Reference (⭐ Recommended)

gpt-image-2-all chat endpoint — best prompt adherence. Same endpoint supports both text-to-image and reference-image editing with native multi-turn iteration.

POST /v1/chat/completions

cURL

text-to-image

curl --request POST \
  --url https://api.apiyi.com/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "gpt-image-2-all",
  "messages": [
    {
      "role": "user",
      "content": "Landscape 16:9 cinematic, old lighthouse at sunset, photorealistic"
    }
  ]
}
'

200

{
  "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
  }
}

⭐ Recommended endpoint: Compared to /v1/images/generations and /v1/images/edits, the chat endpoint offers better prompt adherence and supports both text-to-image and image editing from the same endpoint, with native multi-turn iteration. Enter your API Key in the right-side Playground and pick an example from the dropdown (text-to-image / edit-with-reference / multi-turn).

Pick your mode:

• Text-only messages → text-to-image
• Add image_url (URL or base64 data URL) to messages → edit with reference image
• Keep assistant historical messages → multi-turn iterative editing

🖥️ Browser Playground limitation (when the response contains base64)

This endpoint defaults to an R2 CDN URL (data[0].url) and the Playground displays it fine. In rare cases the response carries base64 (data[0].b64_json), or you pass a large base64 input image via image_url, in which case the response string can reach several MB and the browser Playground may show 请求时发生错误: unable to complete request — the request actually succeeded; the browser just can’t render that much content.

Recommended workflow: when this happens, copy the code sample below and run it locally — the program can read the result from data[0].url or data[0].b64_json (only one of the two appears, never both).

Code Examples

Python (text-to-image)

import requests

API_KEY = "sk-your-api-key"

response = requests.post(
    "https://api.apiyi.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={
        "model": "gpt-image-2-all",
        "messages": [
            {"role": "user", "content": "Landscape 16:9 cinematic, old lighthouse at sunset, photorealistic"}
        ]
    },
    timeout=300  # conservative — absorbs tail latency + image upload/download time
).json()

# Defaults to url; if you switch to b64_json mode, read response["data"][0]["b64_json"]
print(response["data"][0]["url"])

Python (edit with reference image)

import requests
import base64

API_KEY = "sk-your-api-key"

# Use an HTTPS URL or a base64 data URL
with open("photo.png", "rb") as f:
    data_url = "data:image/png;base64," + base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.apiyi.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={
        "model": "gpt-image-2-all",
        "messages": [
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "Turn this image into a watercolor painting"},
                    {"type": "image_url", "image_url": {"url": data_url}}
                ]
            }
        ]
    },
    timeout=300  # conservative — absorbs tail latency + image upload/download time
).json()

# Defaults to url; if you switch to b64_json mode, read response["data"][0]["b64_json"]
print(response["data"][0]["url"])

cURL (text-to-image)

curl -X POST "https://api.apiyi.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-all",
    "messages": [
      {"role": "user", "content": "Landscape 16:9, cyberpunk rainy night street, neon sign reading Hello World"}
    ]
  }'

cURL (edit with reference)

curl -X POST "https://api.apiyi.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-all",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Turn this image into a watercolor painting" },
          { "type": "image_url", "image_url": { "url": "https://example.com/photo.png" } }
        ]
      }
    ]
  }'

Node.js (text-to-image)

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

const response = await fetch("https://api.apiyi.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-image-2-all",
    messages: [
      { role: "user", content: "1024x1024 square logo, minimalist cat line art" }
    ]
  })
});

const data = await response.json();
// Defaults to url; if you switch to b64_json mode, read data.data[0].b64_json
console.log(data.data[0].url);

Node.js (edit with reference)

import fs from "node:fs";

const API_KEY = "sk-your-api-key";
const imgB64 = fs.readFileSync("./photo.png").toString("base64");
const dataUrl = `data:image/png;base64,${imgB64}`;

const response = await fetch("https://api.apiyi.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-image-2-all",
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: "Turn this image into a watercolor painting" },
          { type: "image_url", image_url: { url: dataUrl } }
        ]
      }
    ]
  })
});

const data = await response.json();
// Defaults to url; if you switch to b64_json mode, read data.data[0].b64_json
console.log(data.data[0].url);

About the OpenAI SDK: The request format is OpenAI Chat Completions compatible, but the response format is {data: [{url|b64_json}], created, usage} — there is no choices field. Calling client.chat.completions.create(...) will fail to parse the response. Use the requests / fetch snippets above to read the raw JSON instead.

Parameters Quick Reference

Parameter	Type	Required	Description
model	string	Yes	Fixed: gpt-image-2-all
messages	array	Yes	Conversation messages; supports system / user / assistant roles
messages[].content	string | array	Yes	Plain text (text-to-image) or multimodal array (edit with reference)
stream	boolean	No	Streaming. This model returns one-shot — keep false

Multimodal content part (when content is an array):

Field	Type	Required	Description
type	enum	Yes	text or image_url
text	string	Conditional	Required when type=text
image_url.url	string	Conditional	Required when type=image_url. Accepts https://... or data:image/png;base64,...

Detailed field constraints and allowed values are shown in the right-side Playground. The “Example” dropdown switches between text-to-image / edit-with-reference / multi-turn.

Response Format

The chat endpoint responds with {data: [{url|b64_json}], created, usage}. data[0] returns either url or b64_json, never both. This endpoint defaults to url.

Default url output:

{
  "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
  }
}

b64_json output (rare):

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

Parsing tip: Read data[0].url first; if it’s empty, fall back to data[0].b64_json. The b64_json value already includes the data:image/png;base64, prefix and can be used directly as <img src>.

Why the chat endpoint is recommended

Better prompt adherence

The chat endpoint follows complex instructions, size hints, and typographic requests more reliably

One endpoint, two modes

No need to switch between generations / edits — a single endpoint handles both

Native multi-turn

Keep assistant history and continue refining — same mental model as ChatGPT

Complete SDK ecosystem

Works out-of-the-box with the OpenAI SDK, LangChain, and any Chat-style frontend

Related Resources

Model Overview

Capabilities, pricing, best practices

Text-to-Image API (/v1/images/generations)

OpenAI Images API compatible endpoint

Image Editing API (/v1/images/edits)

Upload reference images via multipart/form-data

Online Playground

Test on imagen.apiyi.com

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

messages · object[] · required

Conversation messages. Supports multi-turn and multimodal content.

Show child attributes

stream · boolean · default: false

Whether to stream the response. This model returns one-shot — keep false. Playground does not support streaming preview.

temperature · number · default: 1

Sampling temperature (minor effect on image generation — default is fine)

Required range: 0 <= x <= 2

Response

200

application/json

Image generated. Defaults to an R2 CDN URL in data[0].url — b64_json is not returned in the same response.

Response shape for the chat endpoint. data[0] returns either url or b64_json, never both. This endpoint defaults to url.

data · object[]

Generated results (this model returns 1 image per call)

Show child attributes

created · integer

Unix timestamp (seconds)

usage · object

Token usage statistics

Show child attributes