Grok Imagine 공식 이미지 생성

개요

Grok Imagine Official은 xAI 이미지 모델을 위한 공식 채널입니다. 요청은 APIYI를 통해 공식 xAI API로 릴레이되며, 가격은 xAI 정가와 동일하고 해상도 및 품질 티어에 따라 과금되며, 매개변수 유효성 검사는 업스트림과 동일합니다. 표준형 grok-imagine-image, 고품질 grok-imagine-image-quality, 최신 grok-imagine-image-2.0(low / medium 품질 티어 지원)의 세 가지 모델을 사용할 수 있습니다.

🔒 이 채널은 신청 후 승인이 필요한 GrokOfficial 그룹 전용입니다Grok Imagine Official은 Default 그룹에 포함되어 있지 않습니다. 이 제품군의 콘텐츠 안전 정책은 플랫폼의 다른 모델과 크게 다르므로, 규정 준수 위험을 방지하고자 권한을 선택적으로 부여하고 있습니다.

누적 소비 금액 $1,000+ 이상인 기존 고객: 고객 지원팀에 문의하여 사용 사례를 설명해 주시면 확인 후 활성화해 드립니다.
그 외 모든 고객: WeCom 고객 지원을 통해 사용 사례와 콘텐츠 모더레이션 제어 조치를 기재하여 신청해 주시면 승인 후 활성화해 드립니다.

GrokOfficial 그룹이 없는 Token은 서비스 장애가 아닌 권한 문제로 인해 503 오류를 반환합니다. 자세한 내용은 아래의 그룹 설정을 참조하십시오.

공식 채널인가요, 리버스인가요? 이 페이지는 공식 채널에 대한 안내입니다. xAI와 동일한 가격, 티어별 과금, grok-imagine-image-2.0 포함, 그리고 현재 1회 호출당 1장의 이미지 생성(텍스트-이미지)만 지원합니다. 이미지 편집, 1회 호출당 여러 장 생성, 또는 해상도에 관계없이 저렴한 고정 가격(이미지당 $0.02 / $0.045)이 필요한 경우 Grok Imagine Reverse를 이용하십시오. 상세 비교는 공식 채널 vs 리버스 비교를 참조하십시오.

모든 이미지 API는 동기식입니다. 비동기 작업 ID가 없으므로 클라이언트 연결이 끊어지면 결과가 유실되더라도 요청에 대한 과금은 그대로 청구됩니다. 테스트 결과 medium 품질 및 2K 해상도의 grok-imagine-image-2.0는 약 60~80초가 소요되므로, 이 모델에 타임아웃을 넉넉하게 설정하십시오. 자세한 내용은 이미지 API 주의 사항 및 모범 사례를 참조하십시오.

텍스트-이미지 API

대화형 Playground를 통해 텍스트 prompt로부터 이미지를 생성합니다.

Grok Imagine Video

동일한 GrokOfficial 그룹 적용 — 초당 과금되는 텍스트-비디오 및 이미지-비디오 생성.

AI 에이전트로 연동하기

이 prompt를 복사하여 Codex / Claude Code / Cursor에 붙여넣으십시오

먼저 이 페이지의 일반 텍스트 버전을 가져온 다음(모든 문서 URL 끝에 .md 추가), 타임아웃 설정, URL 결과 즉시 저장, size 대신 resolution 사용, 호출당 이미지 1개 생성 등의 요구사항이 이미 반영된 귀하의 기술 스택에 맞는 코드를 작성합니다.

이 프로젝트에 Grok Imagine Official 텍스트-투-이미지를 연동/트러블슈팅하십시오.

코드를 작성하기 전에 문서를 읽으십시오: 이 페이지의 일반 텍스트 버전을 확인하려면 https://docs.apiyi.com/en/api-capabilities/grok-imagine-image-official/overview.md 를 가져오십시오. …

모델 하나를 선택하십시오: grok-imagine-image, grok-imagine-image-quality 또는 grok-imagine-image-2.0 …

총 8가지 요구사항 — 전체 버전을 복사하려면 아래 버튼을 사용하십시오

모델 및 가격

요금은 xAI의 정가와 일치하며 이미지당 과금됩니다. 등급은 resolution에 의해 결정됩니다(2.0의 경우 quality 추가):

모델	품질 등급	`1k`	`1.5k`	`2k`
`grok-imagine-image`	—	$0.02	$0.02	$0.02
`grok-imagine-image-quality`	—	$0.05	$0.06	$0.07
`grok-imagine-image-2.0`	`low` (기본값)	$0.04	$0.05	$0.06
`grok-imagine-image-2.0`	`medium`	$0.06	$0.07	$0.08

모델 가격은 공식 사이트 기준에 맞춰 책정되며 변동 사항이 발생할 경우 함께 변경될 수 있습니다. 위 표는 참고용이며, 상단 내비게이션의 모델 가격 탭이 기준이 됩니다: 모델 가격.

과금 안내

기본값: resolution의 기본값은 1k이며, grok-imagine-image-2.0의 기본값은 quality: low(즉, 이미지당 $0.04)입니다.
이미지당 과금, 1회 호출당 1장: 이 채널에서는 n=1 설정을 유지하고, 더 많은 이미지가 필요한 경우 동시 호출하십시오.
실패한 요청은 과금되지 않음: 파라미터 오류(422 / 400), 그룹 접근 권한 없음(503) 및 기타 오류 응답에는 과금되지 않습니다.
usage을(를) 기준으로 대조하지 마십시오: prompt_tokens은(는) 항상 플레이스홀더인 1000 × image count이며, 콘솔 과금 내역이 최종 기준입니다.
구간별 충전 보너스가 추가로 적용됩니다. 대규모 비즈니스 고객은 전용 요금에 대해 영업팀에 문의하실 수 있습니다.

공식 vs 리버스

APIYI는 Grok Imagine을 위한 공식 채널과 리버스 채널을 모두 제공합니다. 두 채널은 그룹, 과금 및 지원 기능에서 차이가 있습니다:

항목	공식 (현재 페이지)	리버스
그룹	`GrokOfficial` (신청 필요)	`Grok_imagine_Reverse` (신청 필요)
과금	xAI 정가와 동일, 해상도 × 품질 등급별 측정	해상도에 관계없이 이미지당 고정 요금
모델	`grok-imagine-image` / `-quality` / `-2.0`	`grok-imagine-image` / `-quality`
해상도 등급	`1k` / `1.5k` / `2k`	`1k` / `2k`
텍스트 투 이미지	✅	✅
이미지 편집 / 다중 이미지 합성	아직 지원하지 않음	✅ 참조 이미지 1–4장
호출당 여러 이미지 생성	아직 지원하지 않음 (`n=1`)	✅ `n` 최대 10장
파라미터 검증	엄격: 범위를 벗어난 값은 422 반환	관대: 유효하지 않은 값은 오류 없이 기본값으로 자동 대체

선택 방법: grok-imagine-image-2.0이 필요하거나, xAI 자체 조건에 따른 과금을 원하거나, 오타 입력 시 명확하게 오류가 발생하기를 원한다면 → 공식 채널을 선택하십시오. 이미지 편집, 호출당 여러 이미지 생성 또는 2K 출력에 대한 최저 가격을 원한다면 → 리버스 채널을 선택하십시오. 두 그룹을 모두 보유하고 각각 고유한 Token으로 호출할 수도 있습니다.

그룹 설정

Grok Imagine Official은 Default 그룹에 포함되어 있지 않습니다. 이 모델은 **GrokOfficial 그룹(xAI와 동일한 가격, 즉 위 표 참고)**에 속해 있으며, 접근 권한을 신청해야 합니다.

이용 가능 대상

고객 유형	신청 방법
누적 사용액 $1,000+ 이상 기존 고객	사용 사례를 기재하여 고객지원팀에 문의, 확인 후 활성화
그 외 모든 사용자	사용 사례 및 콘텐츠 검수 제어 방안과 함께 신청, 승인 후 활성화

신청 방법

WeCom 고객지원 문의

WeCom 고객지원을 통해 신청하거나 [email protected]으로 이메일을 보내십시오. GrokOfficial (Grok Imagine Official) 신청이라고 명시해 주시기 바랍니다.

사용 사례 및 검수 제어 방안 기재

다음 세 가지 사항을 포함해 주십시오: 이미지 사용 목적, 최종 사용자, 귀사 측에서 진행하는 콘텐츠 검토 및 수동 검수 절차. 구체적일수록 검토가 더 빠르게 진행됩니다.

승인 후 Token 그룹 전환

승인이 완료되면 계정에 GrokOfficial을 활성화해 드립니다. 콘솔의 Token 페이지로 이동하여 이 채널에 사용할 Token을 GrokOfficial(으)로 전환하고, 과금 방식을 Pay-as-you-go Priority 또는 Pay-as-you-go(으)로 설정하십시오.

권한 부여 전 확인 사항: GrokOfficial 그룹이 설정되지 않은 Token은 **503 (현재 그룹에 사용 가능한 채널 없음)**을 반환합니다. 재시도해도 해결되지 않으므로, 먼저 그룹을 활성화해야 합니다.Pay-per-request 과금 방식을 사용하지 마십시오: 이 채널은 종량 과금 방식이므로 요청당 지불 Token은 라우팅할 수 없으며 동일하게 503 오류를 반환합니다.

컴플라이언스 안내: 권한이 부여된 후 생성된 콘텐츠에 대한 책임은 호출자에게 있습니다. 현지 법률 및 규정을 준수하십시오. 불법 콘텐츠, 타인의 초상권이나 지식재산권을 침해하는 콘텐츠, 미성년자에게 부적절한 콘텐츠를 생성해서는 안 됩니다. 일반 사용자 대상 서비스의 경우 자체 검수 레이어를 추가하십시오. 관련 참고 자료: 해외 모델 호출 시 컴플라이언스 주의사항. 오남용이 발견될 경우 그룹 접근 권한이 취소됩니다.

기술 사양

항목	사양
모델 ID	`grok-imagine-image`, `grok-imagine-image-quality`, `grok-imagine-image-2.0`
엔드포인트	`POST /v1/images/generations` (`application/json`)
해상도 등급	`1k` (기본값) / `1.5k` / `2k`
화면 비율	일반: `1:1` (기본값) / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3`
품질 등급	`grok-imagine-image-2.0` 전용: `low` (기본값) / `medium`
호출당 이미지 수	`n=1`
응답 형식	`url` (기본값) 또는 `b64_json`
매개변수 유효성 검사	엄격함 — 범위를 벗어난 `resolution` / `aspect_ratio`는 422를 반환합니다
지연 시간	`grok-imagine-image` 약 8초; `-quality` 1k 기준 약 7초 및 2k 기준 12초; `-2.0` `low` 약 15–17초, `medium` 2K 약 60–80초
권장 클라이언트 타임아웃	≥ 360초

주요 매개변수

`resolution` 및 `aspect_ratio` (출력 크기)

이 두 매개변수가 함께 출력 픽셀 수를 결정합니다. 몇 가지 실제 측정 결과는 다음과 같습니다:

모델	요청	실제 출력
`grok-imagine-image`	`1k` + `3:2`	1248×832 (JPEG)
`grok-imagine-image-quality`	`2k` + `9:16`	1584×2816 (PNG, 약 6.7 MB)
`grok-imagine-image-2.0`	`1.5k` + `16:9` + `medium`	1792×1008

size이 아닌 resolution을 사용하십시오이 채널은 OpenAI 스타일의 size(예: "2048x2048")을 해상도 등급에 매핑하지 않습니다. size을 전달해도 오류가 발생하지는 않지만, 이미지는 기본값인 1k로 생성되며 해당 기준으로 과금됩니다. 2K 해상도를 원하시면 resolution: "2k"을 명시적으로 전달하십시오.

잘못된 요청은 명확히 실패합니다: 반대 채널과 달리 이곳의 매개변수 유효성 검사는 xAI와 일치합니다. resolution: "4k" 또는 aspect_ratio: "5:7"와 같이 범위를 벗어난 값은 422를 반환하며 과금되지 않습니다. 422 오류가 발생하면 먼저 이 두 매개변수의 철자를 확인하십시오(모두 소문자: 1k / 1.5k / 2k).

`quality` (`grok-imagine-image-2.0` 전용)

값	참고 사항
`low`	기본값, 더 빠름
`medium`	더 높은 충실도, 이미지당 $0.02 추가, 2K 기준 약 60~80초

high을 전달하면 400(This model only supports the following quality value(s): low, medium, auto)이 반환됩니다. low 또는 medium만 전송하십시오 — auto은 전송하지 마십시오. grok-imagine-image 및 grok-imagine-image-quality은 quality을 받지 않으며, 모델 자체가 충실도를 설정합니다.

`n` (이미지 수)

이 채널에서는 항상 n=1을 전송하십시오. 여러 이미지를 한 번에 생성하려면 여러 요청을 동시에 전송하십시오 — 지연 시간은 일정하므로 동시 실행 수에 따라 선형적으로 확장됩니다.

모범 사례

1k에서 탐색하고 2k에서 완성하십시오

1k에서 prompt를 몇 번 실행하여 방향을 결정한 다음, 2k에서 최종본을 렌더링하십시오. grok-imagine-image-2.0은 medium 및 2K에서 1분 이상 소요되므로, 시행착오를 거치기에는 적합하지 않습니다.

클라이언트 타임아웃을 360초로 설정하십시오

이미지 API는 동기식입니다. 타임아웃을 60초로 설정하면 2.0 medium에서 잦은 오탐 타임아웃이 발생할 수 있으며, 클라이언트에서 중단한 요청에도 여전히 과금됩니다.

구도 설정에는 prompt가 아닌 aspect_ratio를 사용하십시오

해당 매개변수는 실제로 적용되므로, aspect_ratio: "16:9"를 사용하는 편이 prompt에 “가로 구도”라고 작성하는 것보다 훨씬 안정적입니다.

URL 결과는 즉시 저장하십시오

반환된 이미지 링크는 즉시 서버의 자체 스토리지로 다운로드하십시오. 해당 링크를 계속해서 참조하거나 최종 사용자에게 전달하지 마십시오.

편집 시에는 리버스 채널로 전환하십시오

이 채널은 아직 이미지 편집 기능을 제공하지 않습니다. 참조 기반 편집 및 다중 이미지 합성을 수행하려면 /v1/images/edits를 Grok Imagine Reverse에서 사용하십시오.

오류 코드 및 재시도

HTTP	의미	조치 방법
`400`	유효하지 않은 `quality`(`high` 등). 메시지에 허용된 값이 나열됩니다	`low` / `medium`(으)로 변경하십시오. 재시도하지 마십시오
`422`	허용된 범위를 벗어난 `resolution` / `aspect_ratio`	철자 및 대소문자를 확인하십시오. 재시도하지 마십시오
`429`	요청 제한 도달 또는 잔액 부족	지수 백오프로 재시도하고 잔액을 확인하십시오
`503`	Token에 `GrokOfficial` 그룹이 없거나, Token이 요청당 과금 방식을 사용 중입니다	장애가 아닌 권한 문제입니다 — 재시도해도 해결되지 않습니다. 그룹 설정을 확인하십시오

클라이언트 권장 사항: 400 / 422은(는) 결정론적 오류이므로 재시도하는 것은 무의미하며, 대신 알림을 발생시켜야 합니다. 재시도할 가치가 있는 것은 429 및 네트워크 수준 타임아웃뿐이며, 지수 백오프를 적용하여 최대 3회까지만 재시도하십시오. 오류 응답은 과금되지 않습니다.

자주 묻는 질문

모든 호출에서 503이 반환됩니다 — 채널이 다운되었나요?

거의 확실하게 권한 문제입니다. 두 가지 가능성이 있습니다:

Token 그룹에 GrokOfficial 권한이 없습니다: 이 채널은 신청 시 부여됩니다. 그룹 설정을 참고하십시오.
Token의 과금 방식이 요청당 과금입니다: 이 채널은 종량제로 과금되며 요청당 과금 Token에서는 라우팅할 수 없습니다. 과금 방식을 Pay-as-you-go Priority 또는 Pay-as-you-go(으)로 변경하십시오.

size: 2048x2048을 전달했는데 출력 결과가 여전히 1K인 이유는 무엇인가요?

이 채널은 size를 해상도 등급에 매핑하지 않으므로, 이미지가 기본값인 1k로 생성 및 과금됩니다. 대신 resolution: "2k"를 사용하고 aspect_ratio로 구도를 조절하십시오.

이미지를 편집하거나 참조 이미지를 전달할 수 있나요?

이 채널은 아직 이미지 편집 기능을 제공하지 않습니다. /v1/images/generations에 참조 이미지를 전송해도 오류는 발생하지 않지만, 참조 이미지는 무시되며 prompt만으로 새 이미지가 생성됩니다.편집이나 다중 이미지 합성이 필요한 경우, /v1/images/edits에서 1~4개의 참조 이미지를 허용하는 Grok Imagine Reverse에 대한 권한을 얻으십시오.

왜 n=1인가요? 한 번에 여러 장의 이미지를 받으려면 어떻게 해야 하나요?

이 채널은 현재 단일 이미지 출력만 지원합니다. 더 많은 이미지를 원하시면 각각 n=1을 설정하여 여러 요청을 동시에 전송하십시오. 워크플로가 호출당 여러 이미지를 반드시 필요로 하는 경우, Grok Imagine Reverse(n 최대 10개)를 사용하십시오.

grok-imagine-image-2.0은 다른 두 모델과 어떻게 다른가요?

grok-imagine-image-2.0은 xAI의 최신 이미지 모델이며 quality 등급(low / medium)을 추가했습니다. medium은 디테일이 더 정교하지만 생성 속도가 느립니다(2K 기준 약 60~80초). grok-imagine-image은 가장 저렴하며 모든 해상도에서 비용이 동일합니다. grok-imagine-image-quality은 충실도가 더 높고 해상도별 차등 요금이 적용됩니다.먼저 grok-imagine-image 또는 2.0 low에서 파이프라인이 정상 작동하도록 구성한 후, 품질 요구에 따라 상위 등급으로 전환하십시오.

usage의 token 수로 청구 요금을 대조할 수 있나요?

아닙니다. usage.prompt_tokens은 항상 1000 × image count이며, 이는 실제 비용과 무관한 플레이스홀더입니다. 이 채널은 해상도 및 품질 등급에 따라 이미지당 과금되며, 콘솔의 과금 기록이 기준이 됩니다.

공식 OpenAI SDK를 사용할 수 있나요?

네, 가능합니다. 엔드포인트가 OpenAI Images API와 호환되므로, base_url을 https://api.apiyi.com/v1(으)로 지정하고 비표준 필드는 extra_body에 넣으시면 됩니다:

from openai import OpenAI
client = OpenAI(api_key="sk-your-api-key", base_url="https://api.apiyi.com/v1")

resp = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="a red wooden boat on an alpine lake at dawn",
    n=1,
    extra_body={"resolution": "2k", "aspect_ratio": "16:9", "quality": "medium"},
    timeout=360,
)
print(resp.data[0].url)

기초

기본 API

이미지 API (공식)

동영상 API (공식)

멀티모달 이해 API

텍스트 생성

음성 API (공식)

검색 및 안전

Grok Imagine 공식 이미지 생성

개요

텍스트-이미지 API

Grok Imagine Video

AI 에이전트로 연동하기

모델 및 가격

공식 vs 리버스

그룹 설정

이용 가능 대상

신청 방법

기술 사양

주요 매개변수

`resolution` 및 `aspect_ratio` (출력 크기)

`quality` (`grok-imagine-image-2.0` 전용)

`n` (이미지 수)

모범 사례

오류 코드 및 재시도

자주 묻는 질문

관련 문서

​개요

텍스트-이미지 API

Grok Imagine Video

​AI 에이전트로 연동하기

​모델 및 가격

​공식 vs 리버스

​그룹 설정

​이용 가능 대상

​신청 방법

​기술 사양

​주요 매개변수

​resolution 및 aspect_ratio (출력 크기)

​quality (grok-imagine-image-2.0 전용)

​n (이미지 수)

​모범 사례

​오류 코드 및 재시도

​자주 묻는 질문

​관련 문서

개요

AI 에이전트로 연동하기

모델 및 가격

공식 vs 리버스

그룹 설정

이용 가능 대상

신청 방법

기술 사양

주요 매개변수

`resolution` 및 `aspect_ratio` (출력 크기)

`quality` (`grok-imagine-image-2.0` 전용)

`n` (이미지 수)

모범 사례

오류 코드 및 재시도

자주 묻는 질문

관련 문서