Nano Banana

TokenHub 경로로 호출하는 Nano Banana 이미지 생성입니다. 동기 방식으로 처리되고 응답 본문에 결과가 바로 포함됩니다.

기본 정보

항목	값
model	custom-model-gn-v3.1
지원 버전	custom-model-gn-v3.1 / custom-model-gn-v3.1-lite / custom-model-gn-v3.0 / custom-model-gn-v2.5
기본값	model=custom-model-gn-v3.1 / responseFormat=url
지원 작업	텍스트 → 이미지 생성, 이미지 편집
출력 크기	1K / 2K / 4K
지원 비율	16:9 / 1:1 / 4:3 / 3:4 / 9:16
반환 형식	url / b64_json
가드레일 해제 지원	미지원

엔드포인트

항목	값
HTTP 메서드	POST
요청 도메인	https://tokenhub.tencentcloudmaas.com
이미지 생성 및 편집	/v1/wand/gn-image/generation
인증	Authorization: Bearer <API_KEY>
결과 반환	동기. 응답 본문에 생성 결과 포함

리전별 접속 주소

위 주소는 Guangzhou 기준입니다. Singapore, Silicon Valley 등 리전별 주소와 백업 주소는 API 사용 가이드를 참조하세요.

사전 준비

• TokenHub 서비스 활성화와 API Key 발급이 완료되어 있어야 합니다. 절차는 TokenHub Quick Start를 참조하세요.

입력 파라미터

파라미터	필수	타입	설명
model	필수	String	custom-model-gn-v3.1 / custom-model-gn-v3.1-lite / custom-model-gn-v3.0 / custom-model-gn-v2.5
contents	필수	Array	role과 parts로 구성된 콘텐츠 배열
contents.role	선택	String	메시지 역할. user
contents.parts	필수	Array	text 또는 inlineData로 구성된 항목 배열
contents.parts.text	필수	String	생성 프롬프트
contents.parts.inlineData	선택	Object	입력 이미지. 이미지 편집 시에만 사용
contents.parts.inlineData.mimeType	선택	String	입력 이미지 타입. image/png / image/jpeg
contents.parts.inlineData.data	선택	String	입력 이미지. 접근 가능한 URL 또는 Base64 문자열
generationConfig	선택	Object	생성 설정
generationConfig.responseModalities	선택	Array	반환 모달리티. ["IMAGE"]
generationConfig.responseFormat	선택	Object	이미지 출력 설정
generationConfig.responseFormat.image.aspectRatio	선택	String	16:9 / 1:1 / 4:3 / 3:4 / 9:16
generationConfig.responseFormat.image.imageSize	선택	String	1K / 2K / 4K
responseFormat	선택	String	반환 이미지 형식. url / b64_json. 기본값 url
logoAdd	선택	Integer	워터마크 추가 여부. 1은 추가, 0은 미추가. 기본값 0

출력 파라미터

파라미터	타입	설명
candidates	Array	생성 결과 배열
candidates.content.parts.inlineData.data	String	생성 이미지. responseFormat에 따라 URL 또는 Base64
candidates.content.parts.inlineData.mimeType	String	생성 이미지 타입
candidates.finishReason	String	종료 사유. 정상 완료 시 STOP
candidates.index	Integer	결과 순번
modelVersion	String	실제 생성에 사용된 모델 버전
responseId	String	응답 ID
tokenhub_usage.total_tokens	Integer	사용 토큰 수
request_id	String	요청 확인에 사용하는 ID

요청 예시

curl --location 'https://tokenhub.tencentcloudmaas.com/v1/wand/gn-image/generation' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  -d '{
  "model": "custom-model-gn-v3.1",
  "contents": [
    {
      "parts": [
        {
          "text": "Dancing"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ],
    "responseFormat": {
      "image": {
        "aspectRatio": "9:16",
        "imageSize": "2K"
      }
    }
  }
}'

응답 예시

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inlineData": {
              "data": "https://xxxxxx.jpg",
              "mimeType": "image/jpeg"
            },
            "thoughtSignature": ""
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "modelVersion": "gemini-3.1-flash-image",
  "responseId": "uXd8arrMAeu-_uMP7v-g4Ag",
  "tokenhub_usage": {
    "total_tokens": 394260
  },
  "request_id": "5f0b3bf8-3ea8-46b5-b8af-529dabbc25af"
}

이미지 편집

contents.parts에 inlineData를 추가하면 입력 이미지를 참조한 편집이 됩니다. 요청 본문 구조와 응답 구조는 생성과 동일합니다.

입력 파라미터

파라미터	필수	타입	설명
contents.parts.inlineData	필수	Object	입력 이미지
contents.parts.inlineData.mimeType	필수	String	입력 이미지 타입. image/png / image/jpeg
contents.parts.inlineData.data	필수	String	입력 이미지. 접근 가능한 URL 또는 Base64 문자열

생성과 편집은 같은 엔드포인트입니다

텍스트 생성과 이미지 편집은 같은 엔드포인트를 사용합니다. 편집 요청에는 inlineData로 참조 이미지를 전달합니다.

요청 예시

curl --location 'https://tokenhub.tencentcloudmaas.com/v1/wand/gn-image/generation' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  -d '{
  "model": "custom-model-gn-v3.1",
  "contents": [
    {
      "parts": [
        {
          "text": "Dancing"
        },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "https://xxxxxxxxx.png"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ],
    "responseFormat": {
      "image": {
        "aspectRatio": "9:16",
        "imageSize": "2K"
      }
    }
  }
}'

응답 예시

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inlineData": {
              "data": "https://xxxxxx.jpg",
              "mimeType": "image/jpeg"
            },
            "thoughtSignature": ""
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "modelVersion": "gemini-3.1-flash-image",
  "responseId": "kT2pQmR7bvN-_yWL4w-h9De",
  "tokenhub_usage": {
    "total_tokens": 412870
  },
  "request_id": "a7c31e90-6d52-4f18-9b03-72e5cd14f8ba"
}