Skip to main content
POST
Text-to-image: generate images from a text prompt
오른쪽의 대화형 플레이그라운드에서 엔드포인트를 직접 테스트할 수 있습니다. Authorization에 API 키를 입력하고(형식: Bearer sk-xxx), prompt을 입력한 다음, aspect_ratio / resolution를 선택하고 전송합니다.
이 페이지를 사용할 때: prompt만으로 하는 text-to-image 생성입니다 — 이미지 업로드는 포함되지 않습니다. 기존 이미지를 수정하거나 여러 이미지를 합치려면 Image Editing 엔드포인트를 사용하십시오.
⚠️ 이 엔드포인트로 참조 이미지를 보내지 마십시오여기서 image / image_url / images를 전달해도 오류가 발생하지 않습니다. 200을 반환하고 prompt에서 새 이미지를 생성합니다 — 참조 이미지는 조용히 버려지며 여전히 과금됩니다.오류 신호가 없으므로, 보통은 출력이 입력과 전혀 관련이 없다는 것을 누군가 알아차릴 때서야 드러납니다. 참조 이미지가 포함된 모든 워크플로우는 /v1/images/edits를 사용해야 합니다.
⚠️ 잘못된 매개변수는 오류를 발생시키지 않습니다잘못된 aspect_ratio(예: 5:7), resolution(예: 1K, 1024x1024) 및 response_format(예: base64)는 모두 기본값으로 조용히 되돌아가며 여전히 이미지를 반환합니다. 출력이 예상과 다르면 먼저 매개변수 철자를 확인하십시오 — resolution 값은 소문자 1k / 2k입니다.예외가 하나 있습니다: resolution: "4k"503 model_service_unavailable를 반환하며, 이는 티어가 지원되지 않음을 의미하고 채널이 다운되었다는 뜻이 아닙니다. 재시도해도 도움이 되지 않습니다.
모든 이미지 API는 동기식입니다: 비동기 작업 ID가 없으므로, 클라이언트 연결이 끊기면 요청이 아직 과금되는 동안 결과를 잃게 됩니다. 1K는 약 9초, 2K는 약 15~17초가 걸리므로 클라이언트 타임아웃을 360초로 설정하십시오Image API 모범 사례를 참조하십시오.

코드 예제

Python (OpenAI SDK)

Python (raw 요청)

cURL

Node.js (기본 fetch)

브라우저 JavaScript

매개변수 참조

비율별 실제 출력 픽셀 수:
seed은 지원되지 않습니다(오류 없이 수락되지만 아무 효과가 없으며 — 결과를 재현할 수 없습니다), 마스크 inpainting도 지원되지 않습니다. size / quality / style와 같은 OpenAI 스타일 필드는 조용히 무시됩니다.

응답 형식

응답 필드의 함정
  • data[] 항목에는 response_format에 따라 url 또는 b64_json 중 하나만 포함됩니다 — 둘 다 포함되지 않습니다.
  • revised_prompt은 반환되지 않습니다, 또한 respect_moderation / model도 반환되지 않습니다. 존재한다고 가정하지 마십시오.
  • b64_jsondata:image/...;base64, 접두사가 없는 원시 base64입니다 — 직접 디코딩하십시오.
  • created는 항상 0이며 타임스탬프로 사용할 수 없습니다.
  • n > 1을 사용할 때 data 배열에는 여러 항목이 들어 있습니다 — data[0]만 읽지 마십시오.
usage는 정산에 사용할 수 없습니다: prompt_tokens은 실제 prompt 길이와 무관하게 항상 1000 x n입니다. 이 계열은 이미지당 정액 요금($0.02 / $0.045)으로 과금됩니다; 실제 청구 금액은 APIYI 콘솔 과금 기록을 사용하십시오.

인증

Authorization
string
header
필수

API Key created in the APIYI Console

본문

application/json
model
enum<string>
기본값:grok-imagine-image
필수

Model ID. The quality variant delivers higher fidelity at a higher price

사용 가능한 옵션:
grok-imagine-image,
grok-imagine-image-quality
prompt
string
필수

Prompt, English or Chinese. Describe subject, scene, style and lighting in detail

예시:

"A photorealistic red wooden boat moored on a glassy alpine lake at dawn, mist over the water, snow-capped peaks behind, cinematic photography"

n
integer
기본값:1

Number of images, 1-10. Values of 11 or above return 400; 0 is silently treated as 1

필수 범위: 1 <= x <= 10
예시:

1

aspect_ratio
enum<string>
기본값:1:1

Output aspect ratio. Actual pixel dimensions per resolution tier:

Values outside this enum do not raise an error — they silently fall back to 1:1.

사용 가능한 옵션:
1:1,
16:9,
9:16,
4:3,
3:4
예시:

"16:9"

resolution
enum<string>
기본값:1k

Resolution tier. 1k is roughly 0.9-1.05 megapixels and returns JPEG; 2k is roughly 4.2-4.5 megapixels and returns PNG (5-6 MB per image). Both tiers cost the same.

4k returns 503; other invalid values (such as 1K or 1024x1024) silently fall back to 1k.

사용 가능한 옵션:
1k,
2k
예시:

"1k"

response_format
enum<string>
기본값:url

Response format. url returns a direct image link (no signed query params); b64_json returns a raw base64 string (without the data: prefix).

Invalid values silently fall back to the default url.

사용 가능한 옵션:
url,
b64_json
예시:

"url"

응답

Images generated successfully

created
integer

Creation timestamp. Always 0 for this model — do not use it for timing

예시:

0

data
object[]

Array of image results, length equals the requested n

usage
object

Placeholder values — do not use for billing reconciliation. prompt_tokens is always 1000 x n, regardless of actual prompt length. Use the Console billing records instead.