문서 바로가기
목차

Nano Banana Pro API

Generate one image asynchronously per request. Supports text-to-image and image-to-image generation with your Seevio API key.

POST https://api.seevio.ai/v1/images/generations

지원 기능

기능지원하는 값
생성 모드text-to-image, image-to-image
출력 해상도1K, 2K, 4K
화면 비율auto, 1:1, 9:16, 16:9, 3:4, 4:3, 3:2, 2:3, 5:4, 4:5, 21:9
참조 이미지Public HTTPS PNG / JPEG / WebP URLs. Image-to-image requires 1–8 images, each up to 30 MB. Text-to-image requires an empty array.
프롬프트Required non-empty prompt, up to 10000 characters.
출력 형식png, jpg

요금 및 크레딧

Each image costs 4 credits, including all supported resolutions and formats. Credits are reserved on acceptance, settled on success and refunded on failure. Generation times out after 30 minutes; refund_failed means refund recovery is pending.

Request idempotency is not supported. Each valid POST creates a new billable task. If a submission outcome is uncertain, query the returned taskId; retrying POST can create another task.

인증

API 대시보드에서 API 키를 생성하세요. 생성된 전체 API 키 값은 최초 1회만 노출됩니다. 키를 서버 측에 안전하게 보관하고, 모든 API 요청 시 Bearer 토큰으로 포함하여 전송해 주세요.

API 키 생성API 대시보드

기본 URL

https://api.seevio.ai
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

아래 예시 코드를 실행하기 전에 SEEVIO_API_KEY 환경 변수를 설정해야 합니다. JavaScript 예시는 Node.js 기반 서버 환경에서 실행되며, Python 예시는 requests 패키지를 사용합니다.

요청 본문

필드타입필수 여부설명 및 제약 조건
model
string예

모델 ID. Nano Banana Pro을(를) 사용하려면 이 필드를 nano-banana-pro(으)로 설정하세요.

callback_url
string아니요

작업이 성공하거나 실패했을 때 POST 콜백을 수신할 수 있는 공개 HTTPS 엔드포인트 주소입니다. 사설망 주소나 localhost는 지원하지 않습니다.

예시: https://example.com/webhooks/seevio
input
object예

생성에 필요한 설정값입니다. 비어 있지 않은 유효한 prompt 값이 포함되어야 합니다.

입력 파라미터

필드타입필수 여부기본값설명 및 제약 조건
input.prompt
string예—

Required non-empty prompt, up to 10000 characters.

예시: A minimalist ceramic teapot on a stone pedestal, soft studio lighting
input.generation_type
string아니요text-to-image

For image editing, set generation_type to image-to-image and provide image_urls. All other parameters use the same contract.

지원하는 값
text-to-image | image-to-image
input.image_urls
string[]조건부 필수[]

Public HTTPS PNG / JPEG / WebP URLs. Image-to-image requires 1–8 images, each up to 30 MB. Text-to-image requires an empty array.

예시: ["https://example.com/teapot.png"]
input.aspect_ratio
string아니요auto

화면 비율

지원하는 값
auto | 1:1 | 9:16 | 16:9 | 3:4 | 4:3 | 3:2 | 2:3 | 5:4 | 4:5 | 21:9
예시: 1:1
input.resolution
string아니요2K

여기에 제공되는 지원 해상도 목록 중 하나를 선택해 주세요.

지원하는 값
1K | 2K | 4K
예시: 2K
input.output_format
string아니요png
지원하는 값
png | jpg
예시: png

Aspect ratio defaults to auto. Unknown fields, including output quantity, are rejected. Each request generates exactly one image.

빠른 시작

최소한의 파라미터로 아래 요청을 전송하고, 반환된 taskId를 저장한 후 작업 조회 예시를 통해 진행 상황을 확인하세요. 작업 생성 응답에 포함된 credits 값은 가예약된 크레딧 금액을 나타냅니다.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

작업 생성 응답 예시

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 4
}

텍스트로 이미지 생성

Generate one image asynchronously per request. Supports text-to-image and image-to-image generation with your Seevio API key.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

이미지로 이미지 생성

For image editing, set generation_type to image-to-image and provide image_urls. All other parameters use the same contract.

코드 내의 example.com 미디어 URL 주소는 사용자가 직접 접근 가능한 HTTPS 파일 주소로 대체하여 테스트해 주세요. 예시 URL은 API 요청 양식을 보여주기 위한 용도이며 실제로 다운로드 가능한 파일이 아닙니다.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-pro",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

작업 조회

GET https://api.seevio.ai/v1/tasks/{taskId}

예시에 작성된 ID 대신 작업 생성 시 전달받은 taskId를 사용해 주세요. 조회를 요청한 API 키에 귀속된 작업만 반환되며, 소유자가 다르거나 존재하지 않는 ID를 사용해 조회하면 HTTP 404 오류가 발생합니다.

클라이언트 사이드에서 초기 확인 시에는 10~20초 간격으로 폴링을 진행하는 것을 권장하며, HTTP 429 오류가 발생하는 경우 폴링 주기를 더 늘리고 작업 상태가 completed 또는 failed가 되면 조회를 멈추십시오. 프로덕션 환경에서는 웹훅 방식을 적극 권장합니다. 아래의 예시 코드는 각각 단발성 1회 조회를 수행하는 예시입니다.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"
상태Allowed values and requirements
queued작업이 접수되어 처리 대기 중입니다.
generating이미지 생성이 진행 중입니다.
completed작업이 최종 완료되었습니다. 만료되기 전에 data.results에서 결과물 이미지를 다운로드하세요.
failed최종 실패 처리되었습니다. failed_reason과 billing_status 필드를 확인하세요.
Field타입Allowed values and requirements
idstring작업 식별자입니다. 작업 생성 응답에서 받은 taskId 필드 값과 동일합니다.
created_atnumber작업이 생성된 Unix 타임스탬프(초 단위)입니다.
modelstring이 작업에 사용된 퍼블릭 모델 ID입니다.
billing_statusstring정산 상태를 나타내며, 값은 reserved(가예약), charged(실제 결제), refunded(환불 완료), refund_failed(환불 실패) 중 하나입니다.
creditsnumber이 작업에 가예약된 크레딧입니다. 이 금액은 환불 처리 이후에도 이력 보존을 위해 그대로 남아 있으며, 최종 결제 결과는 billing_status의 값을 통해 파악해야 합니다.
failed_reasonstring | null실패한 작업의 구체적인 오류 원인입니다. 정상적으로 처리된 작업의 경우 null이 반환됩니다. 실패 상태의 조회 응답에는 data 필드가 포함되지 않습니다.
dataobject작업 실패가 아닌 경우에 생성되는 객체입니다. 최종 출력 파일 및 상세 처리 내역을 포함합니다.
data.resultsstring[]이미지 URL 배열. 완료 전과 만료 후에는 비어 있습니다.
data.image_expires_atstring | null이미지 만료 시간(ISO 8601). 아직 없으면 null.
data.processing_timenumber | null제공사에서 실제 작업 생성에 소요된 시간(초 단위)입니다. 아직 완료되지 않은 등의 상태에서는 null로 반환될 수 있습니다.

대기 중

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-pro",
  "credits": 4,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

완료됨

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-pro",
  "credits": 4,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

실패함

조회 결과 status=failed로 표시되면 이미지 생성이 실패한 상태입니다. 구체적인 실패 원인은 failed_reason에서, 환불 결과는 billing_status에서 확인하세요. 이 예시의 refunded는 크레딧이 정상적으로 반환되었음을 나타냅니다. credits는 처음 예약된 금액을 유지하며, 응답에 data는 포함되지 않습니다.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-pro",
  "credits": 4,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed."
}

Result links are provided for 30 days after storage. After expiry, results is empty.

웹훅

작업 생성 시 callback_url 파라미터를 추가하면, 이미지 생성이 완료되거나 실패했을 때 지정하신 주소로 JSON POST 요청을 보내드립니다. 콜백 수신 후 15초 이내에 2xx 응답을 반환해 주셔야 합니다. 콜백 전송에 실패하는 경우 재시도가 진행되므로, 수신부에서는 task ID를 기준으로 중복 처리가 되지 않도록 멱등성을 보장하도록 구현해 주세요.

콜백 엔드포인트는 JSON 요청 본문(Content-Type: application/json)을 포함한 POST 요청을 수락해야 합니다.

콜백을 포함하여 작업 생성하기

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Callbacks use the task query response structure; refunded failure notifications also include top-level credits_refunded. Use id to identify the task and status to distinguish completed from failed. Notifications may repeat: process them idempotently by id and status. Callbacks are unsigned; verify the task with the authenticated query endpoint. Delivery failure does not refund a successful task.

작업 완료: 콜백 페이로드 성공

created_at은 이벤트 생성 시간이고 task_created_at은 작업 생성 시간이며 모두 Unix 초 단위입니다. 예시는 권장 필드를 보여 주며 실제 응답에는 추가 필드가 포함될 수 있습니다.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana-pro",
  "credits": 4,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

작업 실패: 콜백 페이로드 실패

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana-pro",
  "credits": 4,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed.",
  "task_created_at": 1789171200,
  "credits_refunded": 4
}

수신 서버 구현 예시

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const imageUrls = callbackData.data.results;
    // Save the image URLs and mark this task as completed in your application.
    console.log(callbackData.id, imageUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

이 Next.js 예시는 JSON 콜백 본문을 읽고 완료 및 실패한 작업을 직접 처리합니다. 실제 애플리케이션에서는 데이터 영속성과 작업 ID 중복 제거 기능을 추가하세요. 콜백 응답을 보내기 전에 시간이 오래 걸리는 작업은 큐(queue)에 대기시키는 것이 좋습니다.

오류 처리

API 요청 처리 중 오류가 발생하면 HTTP 상태 코드와 함께 오류 정보 객체(error)가 전달되며 해당 객체에는 오류 코드(code)와 에러 메시지(message)가 들어 있습니다. 작업 생성이 성공적으로 접수된 후에도 실제 비디오 생성 과정에서 실패가 발생할 수 있으므로, 주기적으로 조회하거나 실패 콜백 처리를 구현해 두어야 합니다.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}
HTTP필드해결 방법
400invalid_request
전송한 JSON 형식의 결함 여부, 프롬프트 누락, 파라미터 값의 유효 범위를 확인하거나 미디어 파일의 HTTPS 다운로드 주소가 정상인지 확인 후 다시 시도하세요.
401invalid_api_key
전달된 Bearer 토큰 및 API 키가 활성화 상태인지 확인해 주세요.
402insufficient_credits
계정에 크레딧을 추가로 충전하거나, 생성 사양을 낮추어 예상 작업 크레딧 소비량을 감축하십시오. 응답 메시지에 필요한 금액과 현재 잔액이 포함되어 안내될 수 있습니다.
403forbidden
오류 메시지에 안내된 계정 수준의 제한 사항을 확인해 주세요.
404not_found
검색에 사용한 작업 ID를 다시 확인해 주세요. 요청한 API 키를 소유한 유저가 생성한 작업만 조회가 가능합니다.
429rate_limited
응답 헤더로 전달된 Retry-After 지정 시간만큼 일시 정지 후 다시 전송을 시도해 주세요.
500internal_error
반환된 에러 메시지 및 API 세부 로그를 자세히 살펴보세요. 동일 요청 재시도 시 불필요하게 가예약 및 청구 처리가 중복 발생할 위험이 있으므로 재시도 시 주의해 주십시오.

Errors use error.code and error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Insufficient provider balance is not a customer 402 error.

호출 비율 제한

태스크 생성: API 키당 기본적으로 분당 최대 100회의 요청이 허용됩니다. 현재 맞춤형 속도 제한은 제공되지 않습니다.

태스크 조회: API 키당 기본적으로 분당 최대 120회의 요청이 허용됩니다. 조회 요청과 태스크 생성 요청은 각각 별도로 계산됩니다.

Image and video creation requests share the same API key rate limit.

호출 초과 발생 시(HTTP 429), 작업 생성은 Retry-After: 60을 헤더로 받으며 조회 요청은 Retry-After: 5를 응답 헤더로 받습니다. 지수 백오프 전략을 채택하고 과도하게 빈번한 폴링은 자제해 주세요.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}