APIVN API로 이미지 생성

API 연결

사이트의 API URL로 Content-Type: application/json과 Authorization: Bearer YOUR_API_KEY를 포함해 요청하세요. x-api-key도 지원합니다.

API key는 서버에서 보관하세요. 예제는 환경 변수를 사용하며 사용자를 대신해 요청을 보내지 않습니다.

read -r -s -p "STALI_API_KEY: " STALI_API_KEY
export STALI_API_KEY
printf '\n'
curl -fsS https://apivn.dev/v1/models -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}"

이미지 모델 선택

req/gpt-image-2 또는 req/gemini-3.0-pro-image를 사용하세요. model을 생략하거나 비워 두면 두 이미지 엔드포인트 모두 req/gpt-image-2를 사용합니다.

GET /v1/models에서 현재 모델 목록과 pricing.per_request를 확인하세요. API key에 선택한 모델의 사용 권한이 있어야 합니다.

설명으로 이미지 생성

model과 이미지 설명 prompt를 포함해 /v1/images/generations로 POST 요청을 보내세요. 예제는 n: 1과 size: 1024x1024로 시작합니다. 처리가 끝나면 JSON을 반환합니다. stream은 false로 고정되며 이 엔드포인트는 SSE 스트림을 반환하지 않습니다.

cURL 예제는 macOS, Linux 또는 WSL의 Bash를 사용합니다. Python은 pip install requests로 라이브러리를 설치하세요. Node.js는 18 이상을 사용하고 코드를 .mjs 파일로 저장한 뒤 내장 fetch를 사용하세요.

curl --fail-with-body --dump-header image-response-headers.txt "https://apivn.dev/v1/images/generations" \
  -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "req/gpt-image-2",
  "prompt": "A small botanical robot tending a seedling, studio product photography, soft natural light, clean ivory background, no text",
  "n": 1,
  "size": "1024x1024"
}'

참조 이미지 편집

/v1/images/edits로 JSON POST 요청을 보내고 비어 있지 않은 prompt와 image를 포함하세요. 이미지는 data URL, base64 문자열 또는 공개 http(s) URL일 수 있습니다. cURL에서는 https://example.com/reference.png를 실제 공개 이미지 URL로 바꾸세요. Python 또는 Node.js에서는 예제를 실행하는 디렉터리에 reference.png를 두세요.

image 대신 image_url, reference_image, ref_image, refImage를 사용할 수 있습니다. 문자열이나 {url: ...} 객체를 지정하며 요청마다 이미지 필드는 하나만 보내는 것이 좋습니다. 편집 엔드포인트는 JSON을 받으며 multipart/form-data는 지원하지 않습니다. 이미지 URL은 공개 접근이 가능하고 인증 정보를 포함하지 않아야 합니다. 내부 주소는 차단됩니다. 참조 이미지는 PNG, JPEG, WebP, GIF를 지원합니다. SDK의 images.edit 메서드가 multipart/form-data를 보내면 그대로 사용하지 마세요. 이 엔드포인트는 JSON이 필요하며 Python requests와 Node.js fetch 예제는 올바른 형식을 사용합니다.

curl --fail-with-body --dump-header image-response-headers.txt "https://apivn.dev/v1/images/edits" \
  -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "req/gpt-image-2",
  "prompt": "Keep the subject and composition, change the background to a warm ivory studio",
  "image": "https://example.com/reference.png",
  "n": 1,
  "size": "1024x1024"
}'

매개변수와 제한

인코딩된 이미지를 포함한 전체 JSON 요청은 최대 20 MiB입니다. Base64는 데이터 크기를 늘립니다. Playground 제한은 별도로 적용됩니다.

반환된 이미지 읽기와 저장

JSON 응답의 data 배열을 읽으세요. 제공업체에 따라 이미지는 b64_json, b64Json 또는 url에 들어 있습니다. 추가 필드는 모델마다 다를 수 있습니다.

{
  "data": [
    {
      "b64_json": "<base64 image bytes>"
    }
  ]
}

base64를 받으면 이미지 파일로 디코딩하거나 실제 형식에 맞는 MIME 유형으로 data URL을 만드세요. 모든 결과가 PNG라고 가정하지 마세요. URL을 받으면 이미지를 다운로드하거나 표시하는 데 사용하세요. URL 유효 기간과 접근 조건은 제공업체에 따라 다릅니다.

문제 확인을 위해 x-apivn-request-id를 저장하세요. 성공 응답에는 x-apivn-model, x-apivn-price-vnd-per-request, x-apivn-cost-vnd 헤더도 포함됩니다.

요청별 요금

이미지 모델은 request 단위로 청구됩니다. 실행 전 GET /v1/models의 pricing.per_request를 확인하세요. 잔액이나 API key 지출 한도로 요청이 차단될 수 있습니다. 응답이나 헤더의 토큰 수로 이미지 모델 요금을 다시 계산하지 마세요. 새로운 요청에는 별도 요금이 발생할 수 있습니다.

시간 초과나 연결 끊김 후 자동으로 재전송하지 마세요. 이전 요청이 이미 처리되었을 수 있습니다. 다시 호출하기 전에 Usage 기록을 확인하고 대조 또는 지원 문의에 사용할 request ID를 저장하세요.

오류를 신중하게 처리

게이트웨이 오류 형식은 {type: "error", error: {type, message, ...}}입니다. HTTP 상태와 error.message를 읽고 request ID가 있으면 저장하세요.

요청 전 확인

API key, 모델 권한과 현재 요금을 확인하세요. 올바른 엔드포인트에 JSON을 보내고 작은 데이터와 이미지 1장으로 시작하세요. base64와 URL 응답을 모두 처리하고 request ID를 저장한 뒤 결과를 확인하고 재호출을 결정하세요.

1. API key와 모델 권한을 확인하세요.
2. /v1/models에서 모델과 가격을 확인하세요.
3. JSON, prompt와 이미지 데이터를 확인하세요.
4. base64와 URL 결과를 모두 처리하세요.
5. Usage 기록을 확인하고 대조 또는 지원 문의용 request ID를 저장하세요.