개요
이것은 Coze platform용 맞춤형 Python 플러그인으로, APIYI의 Nano Banana Pro 모델(gemini-3-pro-image-preview)을 Coze 워크플로우가 직접 호출할 수 있는 노드로 감쌉니다. 이 플러그인에는 완전한 요청 빌더, 세분화된 오류 분류, 콘텐츠 위반 감지, Aliyun OSS 업로드가 포함되어 있으며, 반환되는 것은 바로 표시할 수 있는 공개 URL입니다, 따라서 다운스트림에 추가 전달 노드가 필요하지 않습니다.
프로젝트 정보
- 📦 형식: 코드 패키지로 공유됨(GitHub에 게시되지 않음)
- 👤 작성자: Shuaila1996
- 🎯 플랫폼: Coze CN / 글로벌 맞춤형 플러그인
- 🔌 모델:
gemini-3-pro-image-preview(APIYI를 통해) - 📝 전체 소스 코드는 아래 “플러그인 전체 소스” 섹션에 포함되어 있습니다 — 복사하여 붙여넣기만 하면 되며, 별도의 다운로드는 필요하지 않습니다
핵심 기능
텍스트-이미지 / 이미지-이미지 통합
fileurls가 비어 있는지에 따라 txt2img와 img2img 모드를 자동으로 전환하므로 워크플로에 두 개의 병렬 분기가 필요하지 않습니다다중 참조 편집
이미지 URL 배열을 전달하면 다운로드되어
inline_data로 주입되며 원본 디테일을 유지합니다세분화된 오류 분류
ZERO_CANDIDATES_TOKEN, FINISH_REASON, INLINE_DATA_EMPTY, TEXT_RESPONSE 등을 구분하므로 워크플로 분기가 정확하게 반응할 수 있습니다자동 위반 라벨링
워터마크 제거 / 얼굴 합성 / NSFW / 지식 컷오프 이후 프롬프트에 대해서는 사용자가 추측하게 두지 않고 명확한 거부 유형을 반환합니다
직접 OSS 업로드
base64 결과를 Aliyun OSS로 바로 업로드하므로 워크플로는 공유하거나 저장할 준비가 된 URL을 돌려받습니다
해상도 인식 타임아웃
1K / 2K / 4K(360초 / 600초 / 1200초)에 대해 독립적인 타임아웃을 적용하므로 4K HD 작업이 중간에 끊기지 않습니다
지원되는 APIYI 모델
플러그인 아키텍처

입력 및 출력
입력
출력
배포
1
1단계: APIYI 및 OSS 자격 증명 준비
- APIYI 콘솔에서 APIYI 키를 생성합니다(
sk-로 시작) - 해당 버킷에
oss:PutObject권한이 있는 Aliyun OSS 버킷과 RAM 하위 계정을 생성합니다 AccessKey ID,AccessKey Secret,Bucket name,Endpoint를 기록해 두십시오(예:oss-cn-beijing.aliyuncs.com)
2
2단계: Coze에서 사용자 지정 플러그인 생성
- Coze Workspace → Library → 사용자 지정 플러그인 만들기로 이동합니다
- “Cloud-side plugin — create in Coze IDE”를 선택합니다
- 런타임: Python
- 종속 항목 추가:
requests,oss2
3
3단계: 플러그인 코드 붙여넣기
아래의 “Plugin Full Source” 섹션에서 전체 Python 코드를 Coze IDE에 복사한 다음, 파일 상단의 4개 OSS 구성 줄을 자신의 값으로 업데이트하십시오:
4
4단계: 메타데이터, 입력, 출력 구성
아래와 같이 Input / Output 필드와 필수 플래그를 구성하며, 코드의 
args.input 필드와 일치시킵니다:
5
5단계: 테스트 및 게시
- Coze IDE에서 테스트 매개변수를 입력합니다(권장: 먼저 1K + simple prompt로 OSS 경로를 검증합니다)
- 초록색으로 표시되면 “Publish”를 클릭합니다. 그러면 노드를 이제 어떤 workflow에서도 드래그할 수 있습니다
오류 분류 전략
플러그인은 단순히 불리언만 반환하는 것이 아니라, 실패 원인을 다음 우선순위 순서로 식별하므로 워크플로 분기가 서로 다르게 반응할 수 있습니다:플러그인 전체 소스
아래는 완전한coze-nanobanana-pro.py입니다. 그대로 Coze IDE에 복사할 수 있습니다 — 맨 위의 4개 OSS 구성 라인만 업데이트하면 게시할 준비가 완료됩니다.
coze-nanobanana-pro.py
Coze 워크플로에서 사용하기
게시한 후 플러그인 노드를 Coze 워크플로로 끌어다 놓고 다음과 같이 연결합니다:자주 묻는 질문
왜 base64를 반환하지 않고 OSS에 업로드합니까?
왜 base64를 반환하지 않고 OSS에 업로드합니까?
하위 Coze 워크플로 노드(특히 Feishu 필드 바로가기)는 결과를 이미지 첨부로 변환하려면 일반적으로 접근 가능한 URL이 필요합니다. base64를 반환하면 데이터가 워크플로를 비효율적으로 거치게 되고, Feishu는 이를 직접 렌더링할 수 없습니다. OSS 링크는 장기 보관과 외부 공유도 매우 간단하게 만듭니다.
OSS 설정에 환경 변수를 사용할 수 있습니까?
OSS 설정에 환경 변수를 사용할 수 있습니까?
Coze 커스텀 플러그인은 현재 시스템 환경 변수를 노출하지 않습니다. 권장 방식은 OSS 자격 증명을 파일 상단의 상수로 유지하고 Coze의 플러그인 암호화 기능으로 보호하는 것입니다. 멀티테넌트 워크플로에서는 테넌트별 접두사도 OSS 경로에 기록하십시오.
왜 apikey를 하드코딩하지 않고 전달합니까?
왜 apikey를 하드코딩하지 않고 전달합니까?
호출자마다 다른 키를 배포하기 위해서입니다. 상류에 호출자 이름을 해당 APIYI 키에 매핑하는 “사용자별 API 키” 딕셔너리 노드를 추가하십시오 — 사용량 정산과 접근 제어가 깔끔해집니다.
4K 생성이 계속 시간 초과됩니까?
4K 생성이 계속 시간 초과됩니까?
Nano Banana Pro의 4K 이미지 생성은 실제로 매우 느립니다(보통 5~15분). 플러그인은 이미 4K에 대해 1200초 타임아웃을 설정해 두었습니다. 그래도 시간 초과가 계속되면:
- prompt를 디버깅하려면 2K로 낮추십시오
- APIYI 콘솔에서 요청 제한을 확인하십시오
- 동시 호출 수를 줄이십시오
TEXT_RESPONSE 오류는 어떻게 처리합니까?
TEXT_RESPONSE 오류는 어떻게 처리합니까?
이는 보통 모델이 거부했음을 의미합니다(위반, 연도 차단 등). 플러그인은 유형을 자동 분류합니다: 워터마크 제거 / 페이스 스왑 / NSFW / 연도 > 2025.
error 필드를 사용자에게 표시하십시오 — 재시도하지 마십시오, 결과는 동일합니다.전체 소스 코드는 어디에 있습니까? 바로 복사할 수 있습니까?
전체 소스 코드는 어디에 있습니까? 바로 복사할 수 있습니까?
예. 위의 “플러그인 전체 소스” 섹션에는 완전한
coze-nanobanana-pro.py가 포함되어 있습니다(Shuaila1996이 기여했습니다). 상단의 OSS 설정 4개 줄만 업데이트하십시오 그리고 Coze IDE에 붙여넣으십시오 — 별도의 다운로드는 필요하지 않습니다.추가로 필요하시면:- Feishu 필드 바로가기 → Feishu Bitable AI 이미지 생성 워크플로의 “Feishu 필드 바로가기 전체 소스”를 참조하십시오
- Aliyun FC 코드는 → 같은 문서의 “Aliyun Function Compute 전체 소스”를 참조하십시오
관련 자료
Feishu Bitable AI 이미지 생성
이 Coze 워크플로를 Feishu Bitable에 연결하면 운영자는 행만 채워 일괄 생성할 수 있는 완벽한 동반자입니다.
Nano Banana Pro 문서
전체 Nano Banana Pro API 문서, 과금, 생성 예시
이미지 생성 실패 FAQ
이 플러그인의 오류 코드에 맞춘 Nano Banana 실패 해결 가이드
APIYI 콘솔
API 키를 관리하고 사용량과 잔액을 확인합니다