Grok Imagine Image · API

빠른 시작

세 단계면 됩니다: 작업 제출 → 결과 조회 → 이미지 링크 받기. YOUR_API_KEY를 내 키로 바꾸면 아래 명령을 그대로 실행할 수 있습니다.

1단계 · 제출(작업 ID를 바로 돌려줍니다, HTTP 202)

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-image", "prompt": "새벽녘 눈 덮인 숲속의 붉은 여우, 사실적인 사진", "size": "16:9", "resolution": "2K"}'

응답(HTTP 202)

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "grok-imagine-image"
}

2단계 · status가 succeeded 또는 failed가 될 때까지 2~3초마다 조회

curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"

성공했을 때의 응답

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "grok-imagine-image",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "grok-imagine-image"}
}

3단계 · data[0].url이 이미지(PNG)입니다. 15일 동안 보관되므로 더 오래 쓰려면 내 저장소에 내려받아 두세요.

전체 예제(Python: 제출 → 대기 → 로컬에 저장)

import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. 제출
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "grok-imagine-image",
    "prompt": "새벽녘 눈 덮인 숲속의 붉은 여우, 사실적인 사진",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. 끝날 때까지 3초마다 조회
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. 이미지 내려받기
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("grok-imagine-image.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])

인증

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

콘솔에서 API 키를 만들면 시작할 수 있습니다.

요청 파라미터

POST /v1/images/generations의 요청 본문(JSON):

그 밖의 OpenAI 파라미터(quality, background, output_format, response_format 등)는 가격에 영향을 주지 않으며 적용된다는 보장도 없습니다. 결과는 항상 PNG이며 url로 돌려줍니다.

가격

장당 과금이며 가격은 등급으로만 정해집니다. 비율이나 텍스트-투-이미지 / 이미지-투-이미지 여부와는 관계없습니다. 제출할 때 등급 가격만큼 예약되고, 작업이 실패하면 전액 환불됩니다. 1크레딧 = $0.005.

비율, 해상도와 출력 크기

비율은 size에, 등급은 resolution에 넣습니다. 이미지는 표의 크기 그대로 전달됩니다. 긴 변은 등급으로 정해지고 다른 변은 비율에 따라 계산됩니다. 표에 없는 비율도 같은 규칙으로 쓸 수 있습니다.

• 모델은 가장 가까운 가로형, 세로형, 정사각형 구도로 그리고, 게이트웨이가 이를 가운데 기준으로 잘라 표의 크기로 맞춥니다. 그래서 비율이 3:2, 2:3, 1:1에서 멀수록 가장자리가 더 많이 잘립니다. 게이트웨이는 피사체가 잘리지 않고 가운데에 오도록 프롬프트 뒤에 비율을 설명하는 문장(영어)을 덧붙입니다. 꼭 남아야 하는 내용은 가장자리에서 떨어진 곳에 두세요.
• size에는 픽셀 크기(예: 1536x1024)도 쓸 수 있으며, 이미지는 그 크기 그대로 전달됩니다(긴 변이 4096을 넘으면 비율을 유지한 채 줄입니다). 이때 등급은 resolution으로 정해지고, resolution이 없으면 긴 변으로 정해집니다: 1536 이하는 1K, 2048 이하는 2K, 그보다 크면 4K. resolution은 등급을 올릴 수만 있고 내릴 수는 없으며, 전달 크기도 바꾸지 않습니다. 그러니 작은 크기와 높은 등급을 함께 쓰지 마세요.
• 이 모델은 1K와 2K만 지원합니다. 4K를 요청하면(resolution: "4K" 또는 긴 변이 2048을 넘는 size) 바로 400 unsupported_resolution으로 거절되며 과금되지 않습니다. 2K를 원하면 resolution: "2K"를 보내세요.

이미지-투-이미지와 참조 이미지

• image(한 장) 또는 images(여러 장, 최대 8장이며 8장을 넘는 것은 쓰지 않음)를 보내면 이미지-투-이미지로 실행됩니다. 무엇을 어떻게 바꿀지는 프롬프트에 적으세요. POST /v1/images/edits도 같은 파라미터를 받습니다.
• 두 엔드포인트 모두 JSON 본문만 받고 multipart 파일 업로드는 받지 않습니다. 그래서 OpenAI SDK의 images.edit()은 그대로 쓸 수 없으니, 아래 예시처럼 링크나 base64를 보내세요.
• 참조 이미지는 각각 공개 이미지 URL(http 또는 https), data: URI, 순수 base64 중 하나로 보낼 수 있습니다. 한 장당 16MB 이하이며, JPEG, PNG, WebP 같은 일반적인 형식이면 됩니다.
• URL은 이미지 파일 자체를 내려받을 수 있어야 합니다. 웹 페이지, 로그인이 필요한 주소, 핫링크 방지가 걸린 주소는 안 됩니다. 읽을 수 없는 참조 이미지는 제출할 때 바로 400으로 거절되며, 몇 번째 이미지인지와 이유가 함께 표시됩니다. 작업은 만들어지지 않고 과금되지 않습니다.
• 이 모델은 이미지를 수정할 때 참조 이미지의 비율 그대로 그린 다음, 결과를 size에 맞춰 가운데 기준으로 자릅니다. 그림 전체를 살리려면 size를 참조 이미지와 같은 비율로 지정하세요.
• 참조 이미지는 당사가 대신 호스팅하며 7일 동안 보관합니다.

참조 이미지 2장으로 이미지-투-이미지

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-image", "prompt": "인물은 그대로 두고 배경을 따뜻한 줄조명이 걸린 밤 해변으로 바꾸기", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'

작업 상태와 응답 필드

GET /v1/images/jobs/{id}는 아래 상태를 돌려줍니다. 각 필드의 설명은 비동기 작업에 있습니다. 2~3초마다 조회하거나 웹훅을 쓰세요.

한 계정은 최대 50개 작업을 동시에 생성하며, 그보다 많은 작업은 제출 순서대로 대기합니다. 15분이 지나도 시작되지 않은 작업은 자동으로 실패 처리되고 전액 환불됩니다. 작업 기록은 3일, 이미지 링크는 15일 동안 보관됩니다.

생성 시간

제출부터 결과까지 보통 5~20초 걸립니다. 2K와 이미지-투-이미지는 조금 더 느립니다.

최근 7일간 실제 호출 기준: 중앙값 15 초, 90%가 20 초 안에 완료.

오류와 환불

제출 단계의 오류는 HTTP 4xx / 5xx로 바로 돌아오며, 작업은 만들어지지 않고 과금되지 않습니다. 작업이 접수된 뒤의 실패는 작업 조회 결과로 알려 주며, 예약된 크레딧은 전액 환불됩니다. 전체 코드는 오류 코드에 있습니다.

제출할 때 돌아오는 오류

작업 실패(status가 failed)

조회 대신 웹훅으로 받기

제출할 때 callback_url을 넣으면 작업이 끝나는 즉시(성공이든 실패든) 게이트웨이가 조회 엔드포인트와 똑같은 결과를 그 URL로 보냅니다. 서명이 포함되며, 전송에 실패하면 자동으로 재시도합니다. 콘솔의 「설정 → 웹훅」에서 계정 전체에 쓸 주소를 지정할 수도 있습니다. 웹훅 문서 →

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-image", "prompt": "새벽녘 눈 덮인 숲속의 붉은 여우, 사실적인 사진", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'