Grok Imagine 역방향 이미지 생성 및 편집

개요

Grok 이매진 2는 xAI의 최신 2세대 이미지 모델입니다. 첫 출시 버전보다 파라미터 제어와 편집 기능이 모두 한 세대 발전했습니다. 가로세로 비율과 해상도가 실제로 적용되고, 2K 등급을 사용할 수 있으며, 한 번의 호출로 최대 10개의 이미지를 반환합니다. 또한 참조 편집이 원본 이미지를 실제로 보존합니다. APIYI는 두 가지 변형을 제공합니다: grok-imagine-image(표준) 및 grok-imagine-image-quality(고품질)입니다. 두 변형은 동일한 엔드포인트와 파라미터를 공유하며, 출력 충실도와 가격만 다릅니다.

이 페이지에서는 Grok 이매진 역방향 채널을 다루며 가격은 변경되지 않았습니다: 해상도와 관계없이 이미지당 고정 $0.02 / $0.045이며, 편집과 다중 이미지 출력을 지원합니다.xAI와 동일한 가격으로 해상도 및 품질 등급에 따라 과금되는 공식 채널이 필요하거나 최신 grok-imagine-image-2.0를 사용하려면 Grok 이매진 공식을 참조하십시오. 동영상 생성은 Grok 이매진 동영상을 참조하십시오.

🔒 이 제품군은 기본적으로 공개되지 않습니다 — 전용 Grok_imagine_Reverse 그룹에 대한 액세스가 필요합니다Grok 이매진 2는 완전히 통합되어 안정적으로 작동하지만 Default 그룹에는 포함되지 않습니다. 콘텐츠 안전 정책이 플랫폼의 다른 모델과 크게 다르며 — 일부 카테고리는 필터링되지 않습니다 — 규정 준수 위험을 제한하기 위해 선택적으로 액세스 권한을 부여합니다.

누적 지출액이 $1,000 이상인 기존 고객: 지원팀에 문의하여 사용 사례를 설명하면 확인 후 활성화해 드립니다
그 외 모든 사용자: WeCom 지원을 통해 사용 사례와 콘텐츠 조정 제어 방식을 설명하여 신청하십시오. 요청이 승인되면 해당 계정에서 활성화해 드립니다

Grok_imagine_Reverse 그룹이 없는 토큰으로 모델을 호출하면 **503**이 반환됩니다. 이는 장애가 아닌 권한 문제입니다. 신청 및 구성 방법은 아래의 그룹 설정을 참조하십시오.

주요 특징: 해상도를 무시하는 요청당 고정 가격(xAI는 2K 품질 등급에 $0.07을 책정하지만, 당사는 어느 경우든 $0.045를 부과하여 정가의 약 64% 수준), 실제로 적용되는 가로세로 비율 5개 x 해상도 등급 2개, 호출당 최대 10개의 이미지, 아트 스타일·구도·색상 팔레트·피사체의 정체성을 보존하는 고충실도 참조 편집을 제공합니다. 1K 이미지를 생성하는 데 약 9초가 걸립니다.

모델 ID에는 2이 포함되지 않습니다. 제품 이름은 Grok 이매진 2이지만 호출할 모델 이름은 grok-imagine-image 및 **grok-imagine-image-quality**입니다. 존재하지 않는 모델이므로 **grok-imagine-2-image**으로 작성하지 마십시오. 해당 값을 사용하면 503이 반환됩니다.

📌 먼저 읽어 보십시오: 참조 이미지는 편집 엔드포인트 /v1/images/edits에서만 작동하며 텍스트-이미지에서는 작동하지 않습니다.image / image_url / images를 /v1/images/generations에 전달하면 정상적인 이미지와 함께 200이 반환되지만, 참조 이미지는 조용히 무시되고 오류가 전혀 발생하지 않은 상태로 계속 과금됩니다. 아래의 엔드포인트를 참조하십시오.

모든 이미지 API는 동기식입니다. 비동기 작업 ID가 없으므로 클라이언트 연결이 끊기면 요청에 대한 과금은 계속되는 동안 결과가 손실됩니다. 넉넉한 타임아웃을 설정하십시오. 자세한 내용은 이미지 API 모범 사례를 참조하십시오.

텍스트-이미지 API

텍스트 prompt에서 이미지를 생성하며, 실시간 테스트를 위한 대화형 플레이그라운드를 제공합니다.

이미지 편집 API

참조 이미지와 지침을 업로드하며, 1~4개 이미지 융합 및 플레이그라운드를 지원합니다.

AI 에이전트에게 통합을 맡기기

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

먼저 이 페이지의 일반 텍스트 버전을 가져온 다음(모든 docs URL 뒤에 .md을 추가), 프로젝트에서 사용하는 자체 스택으로 코드를 작성합니다. 타임아웃, 결과 URL 즉시 재호스팅, 참조 이미지를 조용히 무시하면서도 과금하는 엔드포인트, 그리고 size이 아무 작업도 하지 않는다는 사실이 이미 요구사항에 포함되어 있습니다.

이 프로젝트에 Grok Imagine 2 텍스트-이미지 생성 및 이미지 편집을 통합하고 문제를 해결하십시오.

코드를 수정하기 전에 문서를 읽으십시오. 이 페이지의 일반 텍스트 버전을 가져오려면 https://docs.apiyi.com/en/api-capabilities/grok-imagine-image/overview.md를 가져오십시오. 매개변수 세부 정보를 더 확인하려면 .md을 추가하십시오 …

모델 이름: 표준 등급은 grok-imagine-image이고 고충실도 등급은 grok-imagine-image-quality입니다. 모델 ID에는 d …

총 9개의 요구사항이 있습니다. 아래 버튼을 사용하여 전체 프롬프트를 복사하십시오.

이 프롬프트가 방지하는 문제

요구사항	방지하는 문제
참조 이미지는 편집 엔드포인트에만 사용	참조 이미지를 `/v1/images/generations`에 보내면 200이 반환되고 참조 이미지는 조용히 삭제되지만 비용은 계속 청구됩니다 — 아무 오류도 발생하지 않기 때문에 여기서 가장 비용이 큰 함정입니다
`size`는 절대 보내지 않기	조용히 무시되므로 크기를 설정했다고 생각하지만 1024×1024 정사각형을 받게 됩니다
숫자 2가 없는 모델 ID	`grok-imagine-2-image`은 503을 반환하므로 장애처럼 보이지만 실제로는 잘못된 이름일 뿐입니다
고충실도는 매개변수가 아니라 모델	이 모델에는 `quality` 매개변수가 없으며, 보내도 조용히 무시됩니다
`usage`에서 비용을 대조하지 않기	`prompt_tokens`가 n의 1000배로 고정된 플레이스홀더이므로 콘솔 과금 기록을 사용하십시오
타임아웃을 여전히 360초로 설정	약 15초의 지연 시간 때문에 타임아웃을 너무 짧게 설정하게 되고, 그러면 피크 시간에 타임아웃이 발생합니다 — 연결이 끊긴 요청에도 여전히 과금됩니다. 이미지 API 핵심 사항 및 모범 사례를 참조하십시오

APIYI에서 Grok Imagine 2를 사용하는 이유

OpenAI 호환 형식

표준 /v1/images/generations 및 /v1/images/edits 엔드포인트입니다. 요청 본문과 응답 필드가 OpenAI Images API와 일치하므로 공식 OpenAI SDK를 바로 사용할 수 있어 마이그레이션 작업이 전혀 필요하지 않습니다.

동시 실행 수 제한 없음

RPM/RPD 하드 제한이 없습니다. 채널 용량이 충분하여 100 RPM에서 안정적으로 측정되었으므로 배치 작업을 선형적으로 확장할 수 있으며, 쿼터 요청이나 자체적인 속도 제한이 필요하지 않습니다.

단일 요금, 예측 가능한 비용

해상도와 무관하게 이미지당 고정 요금이 적용됩니다. xAI는 1K 품질 등급에 $0.05, 2K에 $0.07을 책정하지만, 당사는 단일 요금 $0.045를 부과합니다. 이는 **2K 기준 정가의 약 64%**입니다. 정확한 이미지 수를 기준으로 예산을 책정하고 충전 보너스를 함께 적용하여 비용을 더 낮출 수 있습니다.

전 세계 액세스, 제한 없음

해외 서버나 프록시가 필요하지 않습니다. 중국 본토 데이터 센터, 가정용 광대역 및 해외 노드에서 모두 api.apiyi.com에 직접 연결할 수 있습니다.

완전한 모델 생태계

Nano Banana 2, GPT-Image-2, Seedream, FLUX와 Grok 텍스트 모델도 사용할 수 있습니다.

전문 지원

당사 팀은 이미지 생성 작업을 깊이 이해하고 있으며, PoC부터 프로덕션 배포까지 엔터프라이즈 고객을 지원할 수 있습니다.

핵심 기능

두 가지 해상도 등급

1k 약 1메가픽셀, 2k 4.2~4.5메가픽셀(16:9에서 2816x1584) — 가격이 동일하므로 2K가 더 유리합니다

5가지 종횡비

1:1 / 16:9 / 9:16 / 4:3 / 3:4이며, 측정된 픽셀 크기가 정확히 일치합니다

호출당 최대 10개

n 1~10개를 지원하며 한 요청에서 여러 이미지를 반환하므로 일괄 선택에 적합합니다

빠른 생성

1K에서 약 9초, 2K에서 15~17초이며 부하 상황에서도 지연 시간이 안정적이므로 100 RPM도 무리 없이 실행됩니다

실제 참조 편집

요청한 부분만 변경하며 아트 스타일, 구도, 팔레트 및 피사체의 정체성은 그대로 유지됩니다

다중 이미지 융합

편집 엔드포인트는 1~4개의 참조 이미지를 지원하며, 테스트에서는 각 이미지가 피사체를 하나씩 추가하고 첫 번째 이미지가 출력 크기를 결정합니다

두 가지 응답 형식

url 직접 링크 또는 b64_json 원시 base64를 지원하며 두 엔드포인트 모두에서 사용할 수 있습니다

OpenAI SDK 지원

client.images.generate() 및 client.images.edit()을 별도의 HTTP 연결 작업 없이 바로 사용할 수 있습니다

샘플 결과

텍스트-이미지 · SF 장면 (grok-imagine-image; 프롬프트만 사용: 구름 바다 위에 떠 있는 고리 형태의 관측소, 황금빛 석양을 받아 빛나는 금속 선체, 멀리 있는 거대한 가스 행성, 와이드스크린 구도): 10.5초 만에 생성되었으며, 금속 반사가 뛰어나고 구름의 입체감이 설득력 있으며 완전하고 층위가 잘 구성된 구도를 보여줍니다.

Grok Imagine 역채널 텍스트-이미지 샘플: 거대한 가스 행성을 뒤에 두고 구름 위에 떠 있는 고리 형태의 관측소

이미지 편집 · 피사체를 유지한 채 표면 교체 (grok-imagine-image; 참조 이미지는 나무 테이블 위의 스킨케어 병이며, 프롬프트는 나무를 흰색 대리석 조리대로 교체하고 병과 말린 꽃은 정확히 변경하지 않도록 지정): 13.9초 만에 생성되었으며, 대리석 무늬의 방향이 창문으로 들어오는 빛의 방향과 일치하고 병의 윤곽이나 꽃의 형태가 왜곡되지 않았습니다. 이 제품군 중 피사체 충실도가 가장 뛰어납니다.

Grok Imagine 역채널 편집 샘플: 병과 말린 꽃은 그대로 유지한 채 나무 테이블을 흰색 대리석으로 교체

가격

모델	해상도	APIYI 가격	xAI 정가	할인
`grok-imagine-image`	`1k` / `2k`	$0.02 / 이미지	$0.02	정가와 동일
`grok-imagine-image-quality`	`1k`	$0.045 / 이미지	$0.05	정가의 90%
`grok-imagine-image-quality`	`2k`	$0.045 / 이미지	$0.07	정가의 약 64%

과금 참고 사항

해상도는 고려하지 않지만, xAI는 고려합니다. xAI는 1K 품질 등급을 $0.05, 2K를 $0.07로 책정하지만 APIYI는 고정 $0.045를 부과합니다. 따라서 해상도가 높을수록 절약되는 금액이 커지며, 2K에서는 정가의 약 **64%**까지 절약할 수 있습니다.
이미지당: n=4은 프롬프트 길이와 관계없이 4개의 이미지로 과금됩니다.
편집 비용은 텍스트-이미지 생성과 동일하며, /v1/images/edits에는 추가 요금이 없습니다.
usage 블록은 대조에 사용할 수 없습니다. prompt_tokens는 항상 자리 표시자인 1000 x n입니다. 대신 콘솔의 과금 기록을 사용하십시오.

충전 보너스를 적용한 실질 비용

이 할인은 **단계별 충전 보너스**와 중복 적용됩니다(누적 방식이 아니라 단일 충전별로 계산됩니다). 품질 등급을 2K로 적용하면 다음과 같습니다.

충전 등급	크레딧 배수	실질 이미지당 비용	xAI의 $0.07 대비
프로모션 없음(정가)	1.0x	$0.045	정가의 64%
$100 단일 충전(+10%)	1.1x	≈ $0.041	정가의 약 58%
$1,000 단일 충전(+15%)	1.15x	≈ $0.039	정가의 약 56%
$3,000 단일 충전(+20%)	1.2x	$0.0375	정가의 약 54%

일반적인 경우($100 등급)에는 2K 이미지의 비용이 xAI 정가의 약 58%가 되며, 최대 보너스 적용 시 약 54%까지 낮아집니다. 표준 grok-imagine-image도 동일한 방식으로 중복 적용됩니다. 즉, 정가 $0.02가 20% 보너스 적용 시 이미지당 약 $0.0167이 됩니다.

그룹 설정

Grok Imagine 2는 Default 그룹에 속하지 않으며 기본적으로 공개되지 않습니다. 별도의 **Grok_imagine_Reverse 그룹(요율 1.0배, 위의 가격표와 동일)**에 속하며, 액세스 권한을 요청해야 합니다.

그룹 이름 안내: 콘솔에는 이 그룹이 Grok_imagine_Reverse(이전 명칭 Grok_imagine)으로 표시됩니다. 이미 액세스 권한이 있는 토큰은 변경할 필요가 없습니다 — 가격과 호출 방식은 변경되지 않습니다. 별도 그룹으로 운영하는 이유: 이 제품군의 콘텐츠 안전 정책은 플랫폼의 다른 모델과 상당히 다르며, 일부 카테고리는 필터링되지 않습니다. 규정 준수 위험을 제한하기 위해 모든 계정이 액세스할 수 있는 기본 그룹에서 제외하고, 대신 선택적으로 액세스 권한을 부여합니다.

액세스 권한을 받을 수 있는 사용자

고객	액세스 권한 부여 방법
누적 지출액이 $1,000 이상인 기존 고객	지원팀에 문의하여 사용 사례를 설명하면, 확인 후 활성화됩니다
그 외 모든 사용자	사용 사례와 콘텐츠 검토 제어 방식을 설명하는 요청을 제출하면, 승인 후 활성화됩니다

신청 방법

WeCom 지원팀에 문의

WeCom 지원팀을 통해 신청하거나 [email protected]으로 이메일을 보내십시오.

사용 사례와 검토 제어 방식 설명

다음 세 가지를 포함하십시오. 이미지가 어떤 제품에 사용되는지, 최종 사용자가 누구인지, 그리고 귀사에서 어떤 검토 및 사람에 의한 검수를 수행하는지 설명해야 합니다. 요청 내용이 구체적일수록 검토가 빨리 진행됩니다.

토큰을 그룹으로 전환

승인되면 계정에서 Grok_imagine_Reverse을 활성화합니다. 콘솔의 토큰 페이지로 이동하여 이 제품군에 사용하는 토큰을 Grok_imagine_Reverse으로 전환하고, 과금 모델을 Pay-as-you-go Priority 또는 Pay-per-request로 설정하십시오.

액세스 권한이 부여되기 전의 상태: Grok_imagine_Reverse 그룹에 속하지 않은 토큰은 **503 (현재 그룹에 사용 가능한 채널이 없음)**을 반환합니다. 다시 시도해도 해결되지 않습니다 — 먼저 그룹을 활성화해야 합니다.권장 토큰 과금 모델: Pay-as-you-go Priority. 이 제품군은 요청별로 과금되며, 종량제 우선 및 요청별 결제 모두 올바르게 라우팅됩니다 — 종량제 우선을 선택하면 하나의 토큰으로 플랫폼의 다른 토큰별 과금 모델도 함께 사용할 수 있습니다.

규정 준수 안내: 액세스 권한이 부여되면 생성된 콘텐츠에 대한 책임은 호출자에게 있습니다. 자신에게 적용되는 법률을 준수하고, 불법 콘텐츠, 타인의 초상권 또는 지적 재산권을 침해하는 콘텐츠, 미성년자에게 부적절한 자료를 생성하지 마십시오. 소비자 대상 배포의 경우 귀사 측에 추가 검토 계층을 마련할 것을 권장합니다. 관련 참고 자료: 해외 모델 호출 시 규정 준수. 악용이 확인되면 그룹 액세스 권한이 회수됩니다.

기술 사양

항목	사양
모델 ID	`grok-imagine-image`, `grok-imagine-image-quality`
종횡비	5: `1:1` / `16:9` / `9:16` / `4:3` / `3:4`
해상도 등급	`1k` (~0.9-1.05 MP), `2k` (~4.2-4.5 MP)
출력 형식	1K에서 JPEG (~220-300 KB), 2K에서 PNG (~5-6 MB)
호출당 이미지 수	`n` 1-10
참조 이미지	편집 엔드포인트에서 1-4개 (`image[]` 반복 사용; 다섯 번째는 400 반환)
마스크 인페인팅	❌ 지원되지 않음
재현 가능한 `seed`	❌ 지원되지 않음
`revised_prompt` 에코	❌ 반환되지 않음
지연 시간	1K에서 약 9초, 2K에서 약 15-17초
동시 실행 수 / 요청률	제한 없음; 100 RPM에서 안정적으로 측정됨
권장 클라이언트 타임아웃	360초 이상

엔드포인트

기능	메서드	경로	Content-Type
텍스트-이미지	`POST`	`/v1/images/generations`	`application/json`
이미지 편집	`POST`	`/v1/images/edits`	`multipart/form-data`
채팅 방식 생성	`POST`	`/v1/chat/completions`	`application/json`

✅ 편집 엔드포인트에는 multipart/form-data 파일 업로드가 필요합니다/v1/images/edits에 JSON을 전송하면 항상 400을 반환합니다:

request Content-Type isn't multipart/form-data

이는 업스트림 공급업체의 문서에서 통합하는 경우 특히 중요합니다 — 해당 문서에서는 공개 이미지 URL이 포함된 JSON 본문을 설명하지만, 이는 APIYI 게이트웨이를 통해서는 작동하지 않습니다. 대신 이 페이지를 따르십시오: -F "[email protected]"을 사용하여 파일을 업로드합니다. 전체 예시는 이미지 편집 API를 참조하십시오.파일 필드의 이름은 image 또는 image[]이어야 합니다. images / image_file를 사용하면 415가 반환됩니다.

⚠️ 텍스트-이미지 엔드포인트로 참조 이미지를 절대 전송하지 마십시오/v1/images/generations가 image / image_url / images을 수신해도 오류가 발생하지 않습니다. 200을 반환하고 참조 이미지는 완전히 무시한 채 프롬프트만으로 완전히 새로운 이미지를 생성하며 — 평소와 같이 과금됩니다.오류 신호가 없으므로 일반적으로 출력이 입력과 전혀 관련이 없다는 것을 누군가 알아차릴 때까지 드러나지 않습니다. 참조 이미지가 포함된 모든 워크플로는 /v1/images/edits을 사용해야 합니다.

기본 도메인은 https://api.apiyi.com이고, 백업 도메인은 https://b.apiyi.com입니다. 채팅 방식 생성(/v1/chat/completions)도 작동하지만 권장되는 경로는 아닙니다 — 아래 FAQ를 참조하십시오.

GPT-Image-2에서 마이그레이션

이미 GPT-Image-2를 통합한 경우 엔드포인트와 호출 규칙은 동일합니다(/v1/images/generations + /v1/images/edits, OpenAI SDK 호환). 하지만 매개변수 시스템이 다르므로 모델 이름만 바꾸는 방식으로는 작동하지 않습니다. 변경해야 할 사항은 다음과 같습니다.

매개변수 매핑

이 표에서는 GPT-Image-2를 기준으로 사용합니다. gpt-image-2.5-flare / gpt-image-2.5-sunburst은 해당 모델의 매개변수를 공유하므로 매핑이 동일하게 적용됩니다.

항목	GPT-Image-2	Grok Imagine 2	마이그레이션 작업
출력 크기	`size` (`1536x1024`과 같은 명시적 픽셀 크기)	`aspect_ratio` + `resolution`	반드시 다시 작성해야 합니다. `size`는 오류를 발생시키지 않습니다
품질 등급	`quality` (`low`/`medium`/`high`/`auto`)	해당 매개변수 없음 — 모델 이름을 사용합니다	`quality`을 제거하고 `-quality` 변형으로 전환합니다
출력 형식	`output_format` (png/jpeg/webp) + `output_compression`	해당 매개변수 없음 — 형식은 해상도를 따릅니다	둘 다 제거합니다. 1K는 항상 JPEG이고 2K는 항상 PNG입니다
배경	`background` (`opaque`/`auto`)	해당 매개변수 없음	제거합니다
조정 수준	`moderation` (`auto`/`low`)	해당 매개변수 없음	제거합니다
고충실도	`input_fidelity`은 전송하지 않아야 합니다	해당 매개변수 없음	제거합니다
호출당 이미지 수	`n` 1개만 지원	`n` 1~10개 지원	✅ 클라이언트 측 분산 호출 루프를 제거할 수 있습니다
참조 이미지(편집)	최대 16개	최대 4개	⚠️ 4개를 초과하여 전송하는 흐름을 다시 작업해야 합니다
마스크 인페인팅	✅ 지원됨	❌ 지원되지 않음	⚠️ 마스크에 의존하는 흐름은 마이그레이션할 수 없습니다
과금	token당(고급 품질에서 이미지당 약 $0.21)	요청당 고정, $0.02 / $0.045	예산 모델이 사용량 기반에서 이미지당 과금으로 변경됩니다

가장 쉽게 발생하는 세 가지 실수

1. 기본 응답 형식이 반대입니다 — 가장 자주 놓치는 변경 사항GPT-Image-2는 b64_json만 반환하며(url는 없음), Grok Imagine 2는 기본적으로 url를 반환합니다. 파서가 resp.data[0].b64_json을 읽는 경우, 마이그레이션 후에는 None / undefined을 받게 됩니다.다음 두 가지 수정 방법 중 하나를 선택합니다.

기존 코드 유지 → "response_format": "b64_json"를 명시적으로 전달합니다
직접 링크로 전환 → data[0].url을 읽고 다운로드합니다

또한 GPT-Image-2의 usage에는 실제 token 수가 포함되지만, Grok Imagine 2의 usage는 자리 표시자이며(항상 1000 x n), 이 점에 유의해야 합니다. usage를 기반으로 구축된 비용 보고 스크립트는 마이그레이션 후 잘못된 수치를 생성합니다.

2. size은 오류를 반환하지 않고 조용히 실패합니다GPT-Image-2는 입력을 엄격하게 검증하며 잘못된 입력에 대해 일반적으로 400을 반환합니다. Grok Imagine 2는 허용 범위가 넓습니다. size, quality, style과 같은 OpenAI 스타일 필드는 조용히 무시되며, 잘못된 aspect_ratio / resolution 값은 조용히 기본값으로 대체됩니다.따라서 model만 변경하고 size: "1536x1024"를 제거하는 것을 잊으면 요청은 1024x1024 정사각형 이미지와 함께 200을 반환합니다. 매개변수가 무시되었다는 알림은 전혀 표시되지 않습니다.마이그레이션 후 첫 번째 호출에서 출력 픽셀 크기를 확인하여 aspect_ratio / resolution가 실제로 적용되었는지 확인해야 합니다.

3. 더 이상 참조 이미지를 텍스트-이미지 엔드포인트로 전송할 수 없습니다이 문제는 이 모델에만 해당합니다. 참조 이미지를 /v1/images/generations로 전송하면 200을 반환하고 참조 이미지를 조용히 삭제한 뒤 과금까지 진행합니다. 모든 참조 이미지 호출은 multipart/form-data과 함께 /v1/images/edits을 사용해야 합니다. 위의 엔드포인트를 참조하십시오.

이전과 이후

# Before: GPT-Image-2
resp = client.images.generate(
    model="gpt-image-2",
    prompt="Cyberpunk city on a rainy night",
    size="1536x1024",           # <- remove
    quality="high",             # <- remove
    output_format="jpeg"        # <- remove
)
img = base64.b64decode(resp.data[0].b64_json)

# After: Grok Imagine 2
resp = client.images.generate(
    model="grok-imagine-image",           # use grok-imagine-image-quality for higher fidelity
    prompt="Cyberpunk city on a rainy night",
    n=1,
    extra_body={
        "aspect_ratio": "16:9",           # <- replaces size
        "resolution": "1k",               # <- replaces the sizing role of quality
        "response_format": "b64_json"     # <- set explicitly to keep the parser unchanged
    }
)
img = base64.b64decode(resp.data[0].b64_json)

어떤 것을 사용해야 합니까? 마스크 인페인팅, 픽셀 단위로 정확한 사용자 지정 크기 또는 최대 16개의 참조 이미지 결합이 필요한 경우 GPT-Image-2를 계속 사용하십시오. 예측 가능한 비용(이미지당 고정 과금, 2K 추가 요금 없음), 호출당 여러 이미지 생성(n 최대 10개) 또는 편집 시 높은 원본 충실도가 필요한 경우 Grok Imagine 2를 선택하십시오. 두 모델은 함께 사용할 수 있으며, 동일한 Token 호출로 두 모델을 모두 사용할 수 있습니다.

주요 매개변수

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

이 두 값이 함께 실제 출력 픽셀 수를 결정합니다. 측정된 값은 요청과 정확히 일치합니다.

`aspect_ratio`	`resolution: 1k`	`resolution: 2k`
`1:1`	1024x1024	2048x2048
`16:9`	1280x720	2816x1584
`9:16`	720x1280	1584x2816
`4:3`	1152x864	2368x1776
`3:4`	864x1152	1776x2368

두 매개변수는 텍스트-이미지에만 적용됩니다. /v1/images/edits에서는 오류 없이 허용되지만 효과가 없습니다. 편집된 출력은 항상 첫 번째 참조 이미지의 크기와 일치합니다(입력 1280x720, 출력 1280x720. 융합 세트의 순서를 바꾸면 새로운 첫 번째 이미지를 따르도록 출력이 변경됩니다). 출력 크기를 변경하려면 업로드하기 전에 참조 이미지를 자르거나 크기를 조정합니다.

검증은 엄격하지 않으므로 오타가 오류를 발생시키지 않습니다. aspect_ratio의 열거형에 없는 값(예: 5:7, 21:9) 또는 resolution의 열거형에 없는 값(예: 1K, 1024x1024)은 자동으로 기본값으로 대체되며 이미지가 계속 반환됩니다. 잘못된 response_format도 마찬가지로 url로 대체됩니다. 따라서 출력이 예상과 일치하지 않으면 먼저 매개변수의 철자를 확인합니다.한 가지 예외는 resolution: "4k"이며, 503 model_service_unavailable를 반환합니다. 이는 채널이 중단된 것이 아니라 해당 등급이 지원되지 않는다는 의미입니다. 1k / 2k으로 다시 전환합니다.

`n` (호출당 이미지 수)

1~10을 허용합니다. 반환되는 data 배열의 길이는 n와 같으며, 각 이미지에 과금됩니다. 0은 자동으로 1로 처리되고, 11 이상은 400을 반환합니다.

모범 사례

먼저 결정합니다: 생성입니까, 편집입니까?

참조 이미지가 없으면 → /v1/images/generations입니다. 픽셀 하나를 수정하는 경우라도 참조 이미지가 있으면 → /v1/images/edits입니다. 잘못된 엔드포인트를 선택해도 오류가 발생하지 않고 예상하지 못한 이미지가 생성됩니다.

클라이언트 타임아웃을 360초로 설정합니다

이미지 API는 동기식입니다. 2K는 15~17초가 걸리며, 피크 시간대나 콜드 스타트 중에는 더 오래 걸릴 수 있습니다. 60초 타임아웃을 사용하면 계속 과금되고 있는 요청에서 불필요한 실패가 발생합니다.

프롬프트가 아니라 aspect_ratio로 구도를 제어합니다

이 매개변수는 실제로 작동하므로, aspect_ratio: "16:9"이 프롬프트에서 “가로 방향 구도”를 요청하는 것보다 훨씬 안정적입니다.

대역폭에 따라 해상도 등급을 선택합니다

2K는 이미지당 5~~6MB의 무손실 PNG이고, 1K는 220~~300KB의 JPEG로 약 20배 차이가 납니다. 모바일 환경이나 대량 전송에는 1K를 권장합니다. 두 등급의 비용은 동일하므로, 선택 기준은 순전히 품질과 대역폭 간의 절충입니다.

편집할 때 “나머지는 모두 변경하지 않음”이라고 명시합니다

“스카프를 빨간색으로 바꾸고, 나머지는 모두 정확히 동일하게 유지합니다”와 같은 지시가 매우 잘 작동합니다. 모델이 이 제약을 밀접하게 따르며 이미지의 나머지 부분을 보존합니다.

이미지를 결합할 때 이미지를 명시적으로 지칭합니다

image[] 업로드 순서가 “이미지 1 / 이미지 2 / 이미지 3”의 의미를 결정합니다. 모델이 추측하게 두는 것보다 “이미지 1의 주제를 이미지 2의 장면에 배치합니다”라고 작성하는 편이 훨씬 안정적입니다.

재현성을 위해 seed에 의존하지 않습니다

이 모델군은 seed을 지원하지 않으므로, 동일한 프롬프트를 사용해도 호출마다 결과가 달라집니다. 이미지를 다시 생성할 수 있을 것이라고 기대하지 말고, 보관하려는 이미지를 저장해 두십시오.

배치 작업은 바로 동시 실행으로 처리합니다

동시 실행 수 제한이 없으므로 채널 용량이 충분하면 100 RPM도 무리 없이 실행됩니다. 직렬 큐를 구축하거나 추가 쿼터를 요청할 필요가 없습니다.

오류 코드 및 재시도

HTTP	code	의미	권장 처리
`400`	`invalid_image_request`	편집 엔드포인트가 multipart 대신 JSON을 수신함	`multipart/form-data` 업로드로 전환하고 재시도하지 마십시오
`400`	`invalid_request`	잘못된 매개변수 또는 moderation으로 인해 차단된 prompt	두 경우 모두 동일한 코드입니다. 먼저 매개변수를 확인한 다음 prompt를 수정하십시오
`415`	—	편집 엔드포인트에서 지원되지 않는 파일 필드 이름	필드 이름을 `image` 또는 `image[]`로 변경하십시오
`429`	—	요청 제한 초과 또는 잔액 부족	지수 백오프를 적용하고 계정 잔액을 확인하십시오
`503`	`model_service_unavailable`	지원되지 않는 매개변수 등급(예: `resolution: 4k`)	서비스 중단이 아닙니다 — `1k` / `2k`로 되돌리고 재시도하지 마십시오
`503`	—	token에 `Grok_imagine_Reverse` 그룹이 없음	권한 문제이며 서비스 중단이 아닙니다 — 재시도해도 해결되지 않습니다. 그룹 설정을 통해 적용하십시오

클라이언트 지침: 400 및 415는 결정적이므로 재시도해도 의미가 없습니다. 대신 알림을 생성하십시오. 재시도할 가치가 있는 경우는 429 및 네트워크 계층 시간 초과뿐이며, 지수 백오프를 적용하고 최대 3회 시도해야 합니다.400 invalid_request는 “잘못된 매개변수”와 “콘텐츠 차단”을 모두 포함하며, 응답 본문만으로는 두 경우를 구분할 수 없습니다. 실용적인 판단 기준은 지연 시간입니다. moderation 차단은 생성이 시작되기 전에 발생하므로 약 5~6초 후에 반환되며, 이는 성공적인 생성(약 9초)보다 빠릅니다.

FAQ

모든 호출이 503을 반환합니다. 채널이 중단된 것인가요? 어떻게 액세스할 수 있나요?

먼저 어떤 503인지 확인해야 합니다. resolution: "4k"을 전달하면 해당 티어가 지원되지 않는다는 의미입니다(아래 항목 참조). 매개변수가 올바른데도 503이 지속되면 토큰에 Grok_imagine_Reverse 그룹이 없는 경우일 가능성이 매우 높습니다.이 제품군은 기본적으로 공개되지 않습니다. 콘텐츠 안전 정책이 플랫폼의 다른 모델과 상당히 다르고 일부 카테고리는 필터링되지 않으므로, 컴플라이언스 위험을 제한하기 위해 별도의 Grok_imagine_Reverse 그룹으로 관리하며 선택적으로 액세스 권한을 부여합니다. 누적 사용 금액이 $1,000 이상인 기존 고객은 사용 사례를 지원팀에 설명하여 활성화를 요청할 수 있습니다. 그 외 고객은 사용 사례와 적용 중인 콘텐츠 검토 제어 기능을 설명하여 WeCom 지원팀을 통해 신청해야 합니다.전체 절차는 위의 그룹 설정을 참조하십시오.

공급업체 문서에는 JSON으로 나와 있는데, /v1/images/edits에 JSON을 보내면 400이 반환되는 이유는 무엇인가요?

APIYI 게이트웨이의 편집 엔드포인트는 multipart/form-data만 허용하기 때문입니다. 공급업체의 원본 문서에서는 공개 이미지 URL이 포함된 JSON 본문을 설명하지만, 두 방식은 서로 다르므로 이 사이트의 문서를 따라야 합니다.올바른 형식은 파일 업로드입니다.

curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=grok-imagine-image" \
  -F "prompt=Change the scarf to red, keep everything else the same" \
  -F "[email protected]"

장점은 이미지 호스팅이 필요하지 않다는 것입니다. 로컬 파일을 직접 업로드하면 되므로 공개 URL을 준비하는 것보다 간단합니다. 전체 예시는 이미지 편집 API를 참조하십시오.

참조 이미지를 텍스트-이미지에 보냈고 200을 받았는데 결과가 관련 없는 이미지입니다. 이유가 무엇인가요?

이는 예상된 동작이며, 이 모델에서 가장 흔한 실수입니다. /v1/images/generations은 image / image_url / images을 조용히 무시하고 프롬프트만으로 이미지를 생성하며, 평소와 동일하게 과금합니다.오류 신호가 없으므로 《편집 기능이 고장 났다》고 판단하기 쉽습니다. 참조 이미지를 사용하는 모든 워크플로는 /v1/images/edits을 사용해야 합니다.

편집 엔드포인트에서 resolution / aspect_ratio가 적용되지 않는 이유는 무엇인가요?

편집된 출력 크기는 입력 참조 이미지의 크기를 따릅니다. 1280x720을 입력하면 1280x720이 출력되고, 1024x1024를 입력하면 1024x1024가 출력됩니다. 여기에서 resolution 또는 aspect_ratio를 전달해도 오류는 발생하지 않지만 아무런 효과가 없습니다.출력 크기를 변경하려면 업로드하기 전에 참조 이미지를 자르거나 크기를 조정하십시오.

응답에 revised_prompt가 없는 이유는 무엇인가요?

이 제품군은 revised_prompt을 반환하지 않으며, respect_moderation 또는 model와 같은 필드도 반환하지 않습니다. 각 data[] 항목에는 response_format에 따라 url 또는 b64_json 중 하나만 포함되며, 둘 다 포함되는 경우는 없습니다.응답을 파싱할 때 이러한 필드가 존재한다고 가정하지 마십시오.

usage의 토큰 수를 사용하여 과금을 대조할 수 있나요?

아니요. usage.prompt_tokens은 실제 프롬프트 길이와 관계없이 항상 1000 x n이며, 플레이스홀더에 불과합니다.이 제품군은 요청당 이미지 한 장을 기준으로 고정 요율이 적용되어 과금됩니다. 실제 청구 금액은 APIYI 콘솔의 과금 기록을 사용하여 확인하십시오.

1K는 JPEG인데 2K는 PNG인 이유는 무엇인가요? 크기 차이가 매우 큽니다

이는 원본 제공업체의 동작입니다. resolution: 1k은 JPEG(약 220~~300KB)을 반환하고, resolution: 2k은 무손실 PNG(약 5~~6MB)를 반환하므로 대략 20배 차이가 납니다.URL 확장자, HTTP Content-Type 및 실제 바이트는 서로 일치하므로 Content-Type를 기준으로 안전하게 분기할 수 있습니다.대역폭이 중요한 시나리오(모바일, 대량 전송)에서는 1k을 우선 사용하십시오. 두 티어의 비용은 동일하므로 이는 순전히 품질에 관한 선택입니다. 반대로 품질이 필요한 경우에는 2k에 추가 요금이 없으며 정가보다 더 큰 할인이 적용됩니다.

resolution: 4k를 사용하면 503이 반환됩니다. 채널이 중단된 것인가요?

아니요. 4k은 이 제품군에서 지원되지 않는 티어이므로 게이트웨이가 503 model_service_unavailable을 반환합니다. 코드만 보면 장애처럼 보이지만 실제로는 매개변수 문제이므로 재시도해도 소용이 없습니다. 1k 또는 2k로 변경하십시오.1k과 2k만 지원됩니다.

잘못된 매개변수를 전달했는데 오류 대신 잘못된 이미지가 생성되는 이유는 무엇인가요?

이 제품군의 검증은 느슨하게 적용됩니다. 잘못된 aspect_ratio(예: 5:7), resolution(예: 1K, 1024x1024) 및 response_format(예: base64)은 모두 조용히 기본값으로 대체되며, 400 대신 이미지가 반환됩니다.따라서 출력이 예상과 다를 때는 먼저 매개변수 철자를 확인하십시오. 특히 resolution 값은 소문자 1k / 2k입니다.

한 번의 호출로 몇 장의 이미지를 생성할 수 있나요?

n은 1~10을 허용하며, 반환되는 data 배열의 길이는 n과 같습니다. 이미지마다 과금됩니다.0은 조용히 1로 처리되며, 11 이상을 전달하면 400 invalid_request이 반환됩니다.

시드 기반 재현성을 지원하나요?

아니요. seed을 전달해도 오류는 발생하지 않지만 효과가 없습니다. 동일한 seed을 사용한 동일한 프롬프트라도 호출할 때마다 서로 다른 이미지가 반환됩니다.다시 사용할 이미지가 있다면 재생성하려고 하지 말고 저장해 두십시오.

공식 OpenAI SDK로 호출할 수 있나요?

예. 두 엔드포인트 모두 OpenAI Images API와 호환되므로 base_url을 https://api.apiyi.com/v1로 지정하십시오.

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",
    prompt="a red wooden boat on an alpine lake at dawn",
    extra_body={"aspect_ratio": "16:9", "resolution": "1k"}
)

aspect_ratio 및 resolution는 표준 OpenAI SDK 필드가 아니므로 extra_body를 통해 전달하십시오.

동시 실행 수 제한이 있나요? 일괄 생성이 요청 제한에 걸리나요?

동시 실행 수 제한은 없습니다. 큐에 대기 중인 요청을 거부하는 429 없이, 충분한 채널 용량을 기반으로 100 RPM에서 안정적으로 측정되었습니다. 직렬 큐를 구축하거나 추가 쿼터를 요청하지 않고 동시에 호출할 수 있습니다.실제로 중요한 것은 **timeout**입니다. 이미지 API는 동기식이므로 클라이언트 타임아웃을 360초로 설정해야 정상적으로 처리 중인 요청이 중단되는 것을 방지할 수 있으며, 중단되더라도 과금은 계속됩니다.

콘텐츠 검토는 어떻게 작동하며, 차단 여부를 어떻게 감지할 수 있나요?

이 제품군은 콘텐츠 검토를 적용합니다. 차단된 요청은 매개변수 오류와 정확히 동일한 오류 코드와 메시지를 사용하여 400 invalid_request을 반환하므로, 응답 본문만으로는 두 경우를 구분할 수 없습니다.실용적인 판단 기준은 지연 시간입니다. 콘텐츠 검토로 차단된 요청은 약 5~6초 후 반환됩니다(생성 전에 차단됨). 반면 성공적인 이미지 생성에는 약 9초가 걸립니다. 콘텐츠 검토 결과에는 어느 정도 무작위성이 있으므로 경계선상의 콘텐츠는 재시도할 때 동일하게 처리되지 않을 수 있습니다. 한 번의 시도만으로 결론을 내리지 마십시오.매개변수가 올바른지 확인했는데도 400이 계속 발생하면 프롬프트가 콘텐츠 검토를 트리거했을 가능성이 가장 높습니다. 문구를 수정하십시오.

/v1/chat/completions를 통해 이미지를 생성할 수 있나요?

예. 하지만 권장되는 경로는 아닙니다. 엔드포인트는 content이 마크다운 이미지 링크인 표준 채팅 구조를 반환합니다.

![image](https://apac.ossforai.com/...)

이는 Chatbox 또는 LobeChat과 같은 대화형 클라이언트에 적합합니다. 프로그래밍 방식으로 통합하려면 Images API를 사용하십시오(/v1/images/generations 및 /v1/images/edits). 더 풍부한 매개변수를 제공하고 응답 형식이 더 안정적이며 이 문서와 일관됩니다.

​개요

텍스트-이미지 API

이미지 편집 API

​AI 에이전트에게 통합을 맡기기

​APIYI에서 Grok Imagine 2를 사용하는 이유

OpenAI 호환 형식

동시 실행 수 제한 없음

단일 요금, 예측 가능한 비용

전 세계 액세스, 제한 없음

완전한 모델 생태계

전문 지원

​핵심 기능

두 가지 해상도 등급

5가지 종횡비

호출당 최대 10개

빠른 생성

실제 참조 편집

다중 이미지 융합

두 가지 응답 형식

OpenAI SDK 지원

​샘플 결과

​가격

​충전 보너스를 적용한 실질 비용

​그룹 설정

​액세스 권한을 받을 수 있는 사용자

​신청 방법

​기술 사양

​엔드포인트

​GPT-Image-2에서 마이그레이션

​매개변수 매핑

​가장 쉽게 발생하는 세 가지 실수

​이전과 이후

​주요 매개변수

​aspect_ratio 및 resolution (출력 크기)

​n (호출당 이미지 수)

​모범 사례

​오류 코드 및 재시도

​FAQ

​관련 문서

개요

AI 에이전트에게 통합을 맡기기

APIYI에서 Grok Imagine 2를 사용하는 이유

핵심 기능

샘플 결과

가격

충전 보너스를 적용한 실질 비용

그룹 설정

액세스 권한을 받을 수 있는 사용자

신청 방법

기술 사양

엔드포인트

GPT-Image-2에서 마이그레이션

매개변수 매핑

가장 쉽게 발생하는 세 가지 실수

이전과 이후

주요 매개변수

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

`n` (호출당 이미지 수)

모범 사례

오류 코드 및 재시도

FAQ

관련 문서