텍스트-투-이미지 API 레퍼런스

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.5-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.5-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.5-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.5-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.5-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.5-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.5-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.5-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.5-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.5-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.5-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.5-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.5-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.5-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
  }
}

오른쪽의 대화형 Playground는 직접 온라인 테스트를 지원합니다. Authorization 필드에 API 키를 입력하고(형식: Bearer sk-xxx), prompt를 입력한 뒤 전송을 클릭합니다.

범위: 이 페이지는 텍스트-투-이미지 생성용입니다. prompt만 입력하면 되며 이미지 업로드는 필요하지 않습니다. 기존 이미지를 편집하거나 합성하려면 이미지 편집 엔드포인트를 사용하십시오.

🖥️ 브라우저 Playground 제한(기본 b64_json 모드)이 엔드포인트는 기본적으로 response_format: "b64_json"를 사용하므로, 응답에 수 MB 크기의 base64 문자열이 포함되고 브라우저 Playground에 请求时发生错误: unable to complete request가 표시될 수 있습니다. — 요청은 실제로 성공한 것입니다; 브라우저가 이렇게 긴 base64 문자열을 렌더링할 수 없을 뿐입니다.권장 워크플로:

Playground에서 이미지만 확인하고 싶으신가요? "response_format": "url"를 명시적으로 전달하십시오 — 응답은 단일 R2 링크이며 문제없이 렌더링됩니다.
base64가 필요하신가요? 아래 코드 샘플을 복사해 로컬에서 실행하십시오 — 코드가 이미지를 자동으로 디코딩하고 파일로 저장합니다.

모든 이미지 API는 동기식입니다 — 조회할 task ID가 없으며, 클라이언트가 연결을 끊으면 요청은 여전히 과금된 상태로 유지되지만 결과는 사라집니다. 이 모델에는 넉넉한 timeout을 설정하십시오. Image API Essentials & Best Practices를 참조하십시오.

⚠️ 파라미터 지원

size: 이 필드는 효과가 없습니다 — auto나 어떤 구체적인 값을 보내도 오류는 발생하지 않지만, 해당 값은 서버에서 조용히 무시됩니다. 크기는 전적으로 prompt에 의해 결정됩니다:
- prompt에 크기/비율이 언급된 경우(예: “Landscape 16:9”) → 모델이 prompt를 따릅니다
- prompt에 크기 힌트가 없는 경우 → 같은 prompt라도 호출마다 서로 다른 크기가 나오며, 마치 “다른 카드를 뽑는 것”과 같습니다 — 여러 구성을 탐색할 때 유용합니다
- 크기를 엄격하게 고정하려면 gpt-image-2-vip를 사용하십시오(auto + 30개의 명시적 크기 지원)
n / quality / aspect_ratio: ❌ 거부됩니다. 이를 보내면 파라미터 검증 오류가 발생할 수 있습니다.

크기와 비율은 prompt에 직접 작성하십시오. 예:

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

크기 설명은 prompt의 앞부분에 두십시오. 그래야 반영이 더 잘됩니다.

코드 예시

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.5-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 모드(이미지 데이터를 base64로 반환):

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.5-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.5-all",
    "prompt": "Landscape 16:9 cinematic, old lighthouse at sunset",
    "response_format": "url"
  }'

Node.js

import { Agent, setGlobalDispatcher } from "undici";
import { writeFile } from "node:fs/promises";

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

// Image endpoints mean long silences plus MB-scale bodies, while undici's default
// connect timeout is only 10s and is NOT governed by AbortSignal.timeout below
// (different layers) — widen all three explicitly
setGlobalDispatcher(new Agent({
  connect: { timeout: 30_000 },
  headersTimeout: 300_000,
  bodyTimeout: 300_000,
}));

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

const data = await response.json();
// Verified raw base64 (no data: prefix); earlier versions included one, so check first
let b64 = data.data[0].b64_json;
if (b64.startsWith("data:")) b64 = b64.slice(b64.indexOf(",") + 1);
await writeFile("output.png", Buffer.from(b64, "base64"));

위의 undici import는 별도로 설치해야 하며(npm i undici), 기본 제공되는 fetch을 구동하지만 해당 모듈 이름으로 노출되지는 않습니다. 또한 설치한 사본은 setGlobalDispatcher을 통해 기본 제공되는 fetch에 계속 연결됩니다.maxRetries, connectTimeout 및 전체 요청 타임아웃은 서로 다른 계층에 있으며, 잘못된 항목을 구성하는 것이 Node 측에서 가장 흔한 실수입니다. 연결 재설정, UND_ERR_CONNECT_TIMEOUT 또는 프록시 뒤에서 대규모 응답이 잘리는 문제가 발생하는 경우 이미지 API 연결 끊김 문제 해결을 참조하십시오.

브라우저 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.5-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;

매개변수 빠른 참조

매개변수	유형	필수	설명
`model`	문자열	예	`gpt-image-2.5-all` 또는 `gpt-image-2-all` (가격과 동작이 동일함)
`prompt`	문자열	예	프롬프트입니다. 크기/비율/스타일을 여기에 포함합니다
`size`	문자열	아니요	`auto`만 허용됩니다(동일한 프롬프트라도 다양한 크기가 생성됩니다). 크기를 엄격하게 고정하려면 `gpt-image-2-vip`을 사용합니다
`response_format`	문자열	아니요	`b64_json`(기본값, 원시 base64) 또는 `url`(R2 CDN 링크 반환)입니다. 항상 명시적으로 전달합니다

자세한 매개변수 제약 조건과 허용되는 값은 오른쪽 플레이그라운드에 표시됩니다. response_format 필드에서는 드롭다운 선택을 지원합니다.

응답 형식

data[0]는 url 또는 b64_json 중 하나만 반환합니다 — 둘 다는 아닙니다 (response_format에 따라 다릅니다). 이 엔드포인트는 기본값이 b64_json입니다. b64_json 모드 (기본값):

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

url 모드 (명시적인 "response_format": "url"가 필요합니다, R2 CDN 전역 가속 적용):

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

호환성 참고: 2026년 7월 검증됨 — b64_json 필드는 data: 접두사가 없는 원시 base64입니다. 파일을 기록하려면 디코드하거나, 렌더링하기 전에 직접 접두사를 추가하십시오. 이전 버전에는 접두사가 포함되어 있었습니다, 따라서 두 형태를 모두 처리할 수 있도록 항상 먼저 startsWith('data:') 검사를 실행하십시오.

인증

Authorization

string

header

필수

API Key from the API易 Console

본문

application/json

model

enum<string>

기본값:gpt-image-2.5-all

필수

Model name: gpt-image-2.5-all or gpt-image-2-all (same ChatGPT web line, same price and behavior)

사용 가능한 옵션:

gpt-image-2.5-all,

gpt-image-2-all

prompt

string

필수

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

예시:

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

response_format

enum<string>

기본값:b64_json

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

사용 가능한 옵션:

b64_json,

url

응답

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

기초

기본 API

이미지 API (공식)

동영상 API (공식)

멀티모달 이해 API

텍스트 생성

음성 API (공식)

검색 및 안전

텍스트-투-이미지 API 레퍼런스

코드 예시

Python

cURL

Node.js

브라우저 JavaScript(Fetch)

매개변수 빠른 참조

응답 형식

인증

본문

응답

​코드 예시

​Python

​cURL

​Node.js

​브라우저 JavaScript(Fetch)

​매개변수 빠른 참조

​응답 형식

인증

본문

응답

코드 예시

Python

cURL

Node.js

브라우저 JavaScript(Fetch)

매개변수 빠른 참조

응답 형식