curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
--header 'X-APIMart-Response-Version: 2026-07-27' \
--data '{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}'
import requests
import uuid
url = "https://api.apimart.ai/v1/images/generations"
payload = {
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url",
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"X-APIMart-Response-Version": "2026-07-27",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())
const url = "https://api.apimart.ai/v1/images/generations";
const payload = {
model: "grok-imagine-2.0-ext",
prompt: "A red apple on a white ceramic plate, clean studio product photo",
n: 1,
size: "1:1",
resolution: "quality",
response_format: "url",
};
const headers = {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": crypto.randomUUID(),
"X-APIMart-Response-Version": "2026-07-27",
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload),
})
.then(async (response) => {
console.log(response.status, await response.json());
})
.catch((error) => console.error("Error:", error));
{
"code": 202,
"request_id": "2026081111342261665927mpb4IPDb",
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
}
}
{
"request_id": "20260811...",
"error": {
"message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
"type": "invalid_response_format",
"param": "",
"code": "invalid_response_format"
}
}
{
"error": {
"code": 401,
"message": "인증에 실패했습니다. API 키를 확인해 주세요",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "잔액이 부족합니다. 충전 후 다시 시도해 주세요",
"type": "payment_required"
}
}
{
"error": {
"code": 429,
"message": "요청이 너무 많습니다. 잠시 후 다시 시도해 주세요",
"type": "rate_limit_error"
}
}
Grok Imagine 2.0 Ext
Grok Imagine 2.0 Ext 이미지 생성
- 비동기 텍스트 투 이미지. task_id 로 폴링
- 요청당 1–12장. 성공적으로 전달된 이미지당 과금 ($0.08/장)
- URL 출력만 지원. 이미지 투 이미지 / 스트리밍 미지원
- 이미지 URL 유효기간 72시간
POST
/
v1
/
images
/
generations
curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
--header 'X-APIMart-Response-Version: 2026-07-27' \
--data '{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}'
import requests
import uuid
url = "https://api.apimart.ai/v1/images/generations"
payload = {
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url",
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"X-APIMart-Response-Version": "2026-07-27",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())
const url = "https://api.apimart.ai/v1/images/generations";
const payload = {
model: "grok-imagine-2.0-ext",
prompt: "A red apple on a white ceramic plate, clean studio product photo",
n: 1,
size: "1:1",
resolution: "quality",
response_format: "url",
};
const headers = {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": crypto.randomUUID(),
"X-APIMart-Response-Version": "2026-07-27",
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload),
})
.then(async (response) => {
console.log(response.status, await response.json());
})
.catch((error) => console.error("Error:", error));
{
"code": 202,
"request_id": "2026081111342261665927mpb4IPDb",
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
}
}
{
"request_id": "20260811...",
"error": {
"message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
"type": "invalid_response_format",
"param": "",
"code": "invalid_response_format"
}
}
{
"error": {
"code": 401,
"message": "인증에 실패했습니다. API 키를 확인해 주세요",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "잔액이 부족합니다. 충전 후 다시 시도해 주세요",
"type": "payment_required"
}
}
{
"error": {
"code": 429,
"message": "요청이 너무 많습니다. 잠시 후 다시 시도해 주세요",
"type": "rate_limit_error"
}
}
텍스트 투 이미지 · 비동기 작업.
모델명은 고정
POST /v1/images/generations 를 제출한 뒤 작업 상태 조회 로 폴링하세요.모델명은 고정
grok-imagine-2.0-ext. 미지원: 참조 이미지, stream, url 이외의 response_format.객체 레이어 또는 선택 영역 편집은 레이어 및 영역 편집을 참고하세요.
API 키를 브라우저 번들(
VITE_* / NEXT_PUBLIC_*, LocalStorage 등)에 넣지 마세요. 브라우저는 자체 BFF 를 호출하고, APIMart 키는 서버에서 보관하세요.curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
--header 'X-APIMart-Response-Version: 2026-07-27' \
--data '{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}'
import requests
import uuid
url = "https://api.apimart.ai/v1/images/generations"
payload = {
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url",
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"X-APIMart-Response-Version": "2026-07-27",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())
const url = "https://api.apimart.ai/v1/images/generations";
const payload = {
model: "grok-imagine-2.0-ext",
prompt: "A red apple on a white ceramic plate, clean studio product photo",
n: 1,
size: "1:1",
resolution: "quality",
response_format: "url",
};
const headers = {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": crypto.randomUUID(),
"X-APIMart-Response-Version": "2026-07-27",
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload),
})
.then(async (response) => {
console.log(response.status, await response.json());
})
.catch((error) => console.error("Error:", error));
{
"code": 202,
"request_id": "2026081111342261665927mpb4IPDb",
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
}
}
{
"request_id": "20260811...",
"error": {
"message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
"type": "invalid_response_format",
"param": "",
"code": "invalid_response_format"
}
}
{
"error": {
"code": 401,
"message": "인증에 실패했습니다. API 키를 확인해 주세요",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "잔액이 부족합니다. 충전 후 다시 시도해 주세요",
"type": "payment_required"
}
}
{
"error": {
"code": 429,
"message": "요청이 너무 많습니다. 잠시 후 다시 시도해 주세요",
"type": "rate_limit_error"
}
}
기능 및 제한
| 항목 | 계약 |
|---|---|
| 모델 | 고정 grok-imagine-2.0-ext |
| 기능 | 텍스트 투 이미지만 |
| 모드 | 비동기 작업 |
장수 n | 1–12, 기본값 1 |
size | 비율 7종 + 픽셀 별칭 5종 (아래) |
| 출력 | response_format=url 만 (기본값도 동일) |
| 품질 | 공개 필드 resolution. 검증된 값 quality |
| 미지원 | 이미지 투 이미지, stream=true, 공개 quality, style, b64_json / base64 |
| 과금 | 고정 단가. 성공적으로 전달된 이미지에 과금 |
인증 및 권장 헤더
string
필수
Bearer 토큰. API Key 페이지 에서 키를 발급받으세요.
Authorization: Bearer YOUR_API_KEY
| Header | 설명 |
|---|---|
Content-Type | application/json (제출 시) |
Accept | application/json |
Idempotency-Key | 강력 권장. 사용자가 확정한 논리 생성마다 새 UUID. 네트워크 재시도 시 동일 key 와 body 를 재사용해야 함 |
X-APIMart-Response-Version | 안정적인 제출 응답 형태(data.id)를 위해 2026-07-27 권장 |
요청 파라미터
string
필수
고정 값:
grok-imagine-2.0-extboolean
기본값:"false"
이미지 작업을 제출하기 전에 콘텐츠 검토를 실행할지 여부를 지정합니다.
true:omni-moderation-latest로 프롬프트와 입력 이미지를 검토false또는 생략: 검토 요청을 보내지 않으며 검토 비용이나 지연이 추가되지 않음(기본값)
string
필수
프롬프트. trim 후 비어 있으면 안 됩니다. 제출 전에 trim 하세요.
integer
기본값:"1"
이미지 장수:
1–12. 명시적 0 은 오류. 생략 시 1.string
화면 비율. 비율 문자열 권장 (UI 에는 비율만 표시):
픽셀 별칭:
size | 방향 | 전형적 용도 |
|---|---|---|
1:1 | 정사각 | 상품, 아바타 |
2:3 | 세로 | 포스터, 전신 |
3:2 | 가로 | 사진, 넓은 장면 |
3:4 | 세로 | 이커머스, 인물 |
4:3 | 가로 | 디스플레이 아트 |
9:16 | 세로형 | 스토리 / 숏폼 커버 |
16:9 | 와이드 | 배너, 영상 커버 |
1024x1024 (1:1), 1024x1792 (2:3), 1792x1024 (3:2), 720x1280 (9:16), 1280x720 (16:9).화이트리스트 밖 값은 400 invalid_size 를 반환합니다 (예: 1:2, 2:1, 4:5, auto).동일 비율이라도 실제 픽셀은 별칭 표와 다를 수 있습니다 (예:
1:1 이 1408×1408 반환). 반환 이미지를 기준으로 하고, 측정 픽셀로 size 를 다시 쓰지 마세요.string
품질 모드 필드. 검증된 값:
quality.- 생략 가능 (모델은 기본적으로 품질 모드), 또는
- 명시적으로
resolution: "quality"전달
1K / 2K / 4K 픽셀 단계가 아닙니다. 구도는 size 로 제어합니다.공개
quality 필드를 보내지 마세요 — 400 invalid_quality 가 됩니다. resolution 을 사용하세요.string
기본값:"url"
url 만 허용. 생략 가능. b64_json / base64 → 400 invalid_response_format.미지원 파라미터
| 파라미터 | 동작 |
|---|---|
quality | 400 invalid_quality → resolution 사용 |
style | 400 invalid_style |
image_urls / image_with_roles | 400 invalid_image_input |
stream: true | 400 invalid_stream |
response_format: "b64_json" / "base64" | 400 invalid_response_format |
요청 예제
최소
{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo"
}
권장
{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}
제출 응답
X-APIMart-Response-Version: 2026-07-27 권장. 성공 시 HTTP 202. 작업 ID 는 data.id (레거시 data[0].task_id 에 의존하지 마세요).
저장할 항목:
- 폴링용
data.id - 게이트웨이 디버깅용
request_id - 결과 불명 시 안전 재시도를 위한
Idempotency-Key - UI / 지원용 원본 요청 파라미터
멱등성 및 안전 재시도
이미지 생성은 과금 대상입니다 — 강력 권장Idempotency-Key (1–191 인쇄 가능 ASCII. UUID 가 가장 간편. 약 24시간 유지).
| 시나리오 | 동작 | 조치 |
|---|---|---|
| 동일 key + 동일 body 완료됨 | 재생. 헤더 Idempotency-Replayed: true | 동일 작업 ID 사용 |
| 동일 key 처리 중 | 409 idempotency_in_progress + Retry-After | 대기 후 동일 key 와 body 로 재시도 |
| 동일 key, 다른 body | 409 idempotency_key_reused | 새 논리 작업에는 새 key 필요 |
| 결과 불확정 | 409 idempotency_result_indeterminate | 새 key 를 만들지 말고 기존 key 로 조사 |
작업 폴링
GET /v1/tasks/{task_id}?language=ko
Authorization: Bearer YOUR_API_KEY
Accept: application/json
language: zh / en / ko / ja (실패 메시지 로컬라이즈만). 작업 상태 조회 참고.
상태
status | 종료 | 처리 |
|---|---|---|
pending / processing | 아니오 | 폴링 계속 (result 부재는 실패가 아님) |
completed | 예 | result.images 파싱 |
failed | 예 | error.message 표시. cost 는 0 (선과금 환불) |
unknown | 아니오 | 짧게 재시도. 지속 시 작업 ID 와 함께 지원 문의 |
429 시 Retry-After 준수. 작업은 기본 약 3일 보관 — 클라이언트 타임아웃 후에도 작업 ID 를 유지하세요.
완료 예제
{
"code": 200,
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"status": "completed",
"progress": 100,
"created": 1786419262,
"completed": 1786419275,
"actual_time": 13,
"estimated_time": 100,
"cost": 0.08,
"credits_cost": 0.8,
"result": {
"images": [
{
"expires_at": 1786505675,
"url": [
"https://example.com/image/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.jpg"
],
"image_ids": [
"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
]
}
]
}
}
}
url 과 image_ids 파싱
result.images[]
├─ url[] ← 표시/다운로드 권위 필드 (배열)
├─ image_ids[] ← 선택적 불투명 ID
└─ expires_at ← Unix 초. JS Date 는 ×1000
- 표시에는
url[]사용.n>1이면 모든 항목 순회 image_ids.length === url.length일 때만 인덱스로 매칭image_ids가 없어도 표시 가능- 링크 유효기간 72시간 — 빠르게 다운로드.
expires_at도 신뢰
과금
기본 가격 $0.08 / 장 (성공 전달분):n | 예상 기본 금액 |
|---|---|
| 1 | $0.08 |
| 4 | $0.32 |
| 8 | $0.64 |
| 12 | $0.96 |
- 제출 전 UI 는 “예상”으로 표기. 최종 USD 는
data.cost data.credits_cost는 크레딧 뷰 (현재 약 USD × 10)- 요청 장수로 선과금. 성공 장수로 정산 (부분 실패 시 차액 환불)
- 전체 실패:
cost=0, 선과금 환불 resolution으로 가격 키를 만들지 마세요. 이 모델은 장당 고정가
Webhook (선택)
{
"webhook": "https://your-service.example.com/apimart"
}
- 베이스 URL 을 제공. 플랫폼이
{base}/callback호출 - 공개 접근 가능하고 SSRF 검사를 통과해야 함
webhook_secret설정 시 서명은 원본 바이트에 대한hex(HMAC-SHA256(secret, raw_body))- 콜백 본문은 작업 조회의
data와 동일 (추가{code,data}래퍼 없음) - 폴백으로 저빈도 폴링도 유지
자주 발생하는 오류
| HTTP | error.code | 원인 | 조치 |
|---|---|---|---|
| 400 | invalid_request | 빈 prompt / 잘못된 JSON | 입력 검증 |
| 400 | invalid_n | n 이 1–12 밖 | 장수 제한 |
| 400 | invalid_size | size 화이트리스트 밖 | 고정 선택 옵션 |
| 400 | invalid_response_format | url 아님 | 수정 또는 생략 |
| 400 | invalid_quality | 공개 quality 전송 | resolution 사용 |
| 400 | invalid_style | style 전송 | 제거 |
| 400 | invalid_image_input | 참조 이미지 | 모델 전환 |
| 400 | invalid_stream | stream=true | 제거 |
| 400 | invalid_idempotency_key | 잘못된 key | UUID 사용 |
| 401 | 인증 실패 | 잘못된 key | 서버 자격 증명 수정 |
| 402 | 결제 필요 | 잔액 부족 | 충전 |
| 409 | idempotency_* | 멱등성 충돌 | 위 표 참고 |
| 429 | 속도 제한 | 너무 빠름 | Retry-After 준수 |
| 5xx | 서버 오류 | — | Idempotency-Key 유지. 무분별 교체 금지 |
error.message 를 우선 사용. 원시 인증 내부 정보를 최종 사용자에게 노출하지 마세요.
1.5 와의 차이 (요약)
| 항목 | Grok Imagine 1.5 | 2.0 Ext |
|---|---|---|
| 모델 | grok-imagine-1.5-apimart 등 | grok-imagine-2.0-ext |
| 이미지 투 이미지 | 지원 (1.5 문서 참고) | 미지원 |
| 장수 | 1.5 문서 참고 | 1–12 |
| 품질 필드 | 1.5 문서 참고 | resolution (quality). 공개 quality 불가 |
| 출력 | 1.5 문서 참고 | URL 만 |
| URL 유효기간 | 1.5 문서 참고 (종종 24h) | 72시간 |
| 단가 | 1.5 문서 참고 | $0.08 / 장 |