이미지 생성

POST /v1/images/generations

이미지를 생성합니다. 기본은 동기로, 이미지가 나올 때까지 기다렸다가 응답하며 형태는 OpenAI 의 images/generations 와 같아 OpenAI SDK 와 중계 게이트웨이에서 그대로 쓸 수 있습니다. async: true 를 주면 비동기로 바뀌어 즉시 작업 id를 받고 GET /v1/tasks/{id} 로 결과를 가져옵니다. n이 2 이상이면 독립된 작업이 n개 생성되며 각각 따로 과금됩니다.

요청 파라미터

파라미터	타입	설명
prompt	string	필수. 이미지 설명
model	string	/v1/models 의 모델 id. 생략 시 기본 모델
n	integer	생성 장수 1~4. 기본 1
size	string	화면 비율 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4. 기본 1:1. 1024x1024, 1792x1024 같은 픽셀 표기도 받아 가장 가까운 비율로 맞춤
quality	string	화질 1k \| 2k \| 4k. 기본 1k. spec 지정 시 그쪽이 우선. OpenAI 표기도 인식: standard / low / auto 는 1k, medium / hd / high 는 2k
spec	string	모델 specs[].key 에서 고르는 사양 키
reference_images	string[]	참조 이미지 주소. 모델의 max_reference_images 초과분은 잘림
async	boolean	기본 false 로 이미지를 기다림. true 면 즉시 작업 객체를 반환하므로 /v1/tasks/{id} 를 직접 폴링

인식할 수 없는 값은 요청 전체를 실패시키지 않고 기본값으로 되돌립니다(모르는 size 는 1:1 로 생성). 오류가 되는 경우는 prompt 가 비었거나, 금지어에 걸렸거나, 한도에 도달했거나, 크레딧이 부족할 때뿐입니다. response_format 은 지원하지 않으며 결과는 항상 url 로 반환합니다.

요청 예시 (동기)

bash

curl https://open.pikpikgo.com/v1/images/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "비 내리는 사이버펑크 야간 거리, 네온 반사",
    "size": "16:9",
    "quality": "2k",
    "n": 1
  }'

응답 예시 (동기)

json

{
  "created": 1786000246,
  "data": [
    { "url": "https://cdn.pikpikgo.com/ai/xxxx.png", "revised_prompt": "비 내리는 사이버펑크 야간 거리, 네온 반사" }
  ],
  "id": "2608101909450810293847",
  "object": "image.generation",
  "model": "img-std-1",
  "status": "succeeded",
  "n": 1,
  "credits": 10,
  "tasks": [
    {
      "id": "2608101909450810293847",
      "status": "succeeded",
      "data": [{ "url": "https://cdn.pikpikgo.com/ai/xxxx.png", "revised_prompt": "비 내리는 사이버펑크 야간 거리, 네온 반사" }]
    }
  ]
}

항목	설명
created	응답 타임스탬프
data	생성 결과. 각 항목에 url 과 revised_prompt. n>1 이면 여러 개
id	주 작업 id (n>1 이면 첫 번째 하위 작업)
status	succeeded. 일부만 성공해도 이 값이므로 data 개수와 n을 직접 비교
credits	이번에 차감된 총 크레딧
tasks	모든 하위 작업. 각각의 error 와 결과 포함

동기 호출은 연결을 계속 붙잡습니다. 한 장에 30초 이상 걸리는 경우가 많으니 클라이언트 타임아웃을 300초까지 늘리세요. 300초를 넘기면 서버가 504 generation_timeout 을 반환하지만 작업은 계속 돌고 크레딧도 환원되지 않으므로, 메시지에 있는 작업 id로 /v1/tasks/{id} 에서 나중에 받아올 수 있습니다. 전부 실패하면 502 generation_failed 이며 크레딧은 자동 환원됩니다.

비동기 사용법

배치, 높은 동시성, 지연에 민감한 호출에 적합합니다. 제출 즉시 응답하며 status 는 queued, data 는 비어 있습니다.

bash

curl https://open.pikpikgo.com/v1/images/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "비 내리는 사이버펑크 야간 거리, 네온 반사",
    "size": "16:9",
    "quality": "2k",
    "n": 1,
    "async": true
  }'

json

{
  "id": "2608101909450810293847",
  "object": "image.generation",
  "created": 1786000185,
  "model": "img-std-1",
  "status": "queued",
  "n": 1,
  "credits": 10,
  "tasks": [
    { "id": "2608101909450810293847", "status": "queued", "data": [] }
  ],
  "data": []
}

n>1 이면 tasks 를 순회하세요. id 하나만 폴링하면 나머지 이미지를 놓칩니다.