Pipedream을 GenderAPI.io V2에 연결하기

API 규격에 맞는 Pipedream 연결 방식 선택하기

이 가이드의 HTTP 설정은 https://api.genderapi.io/api/v2/gender에서 GenderAPI.io V2를 호출합니다. JSON 본문에 type과 value를 보내세요. 추정 결과는 data에, 요청과 차감 정보는 meta에 들어 있습니다. 기본 제공 커넥터에는 별도의 규격이 있으며, 아래에서 설명합니다.

2026년 9월 26일에 검토한 Pipedream의 공개 GenderAPI.io 컴포넌트는 예전 기본 URL인 https://api.genderapi.io/api를 사용하며, name 또는 email, 선택 사항인 country, API 키를 쿼리 문자열 매개변수로 보냅니다. 게시된 구현은 V1 커넥터이며, JSON을 사용하는 V2 엔드포인트가 아닙니다.

기존 기본 제공 액션을 그 자체의 규격대로 유지하거나, V2용 일반 HTTP 단계를 추가할 수 있습니다. 기본 제공 연결 계정의 자동 인증이 이 별도의 V2 요청에도 맞는다고 가정하지 마세요. 이 설정은 Bearer 헤더를 명시적으로 사용합니다.

계정과 원본 레코드 준비하기

이 예시는 이메일 주소를 기준으로 Twilio SendGrid 레코드를 보강합니다. 원본 앱과 대상 앱에 대한 접근 권한, GenderAPI.io 계정 API 키, HTTP 액션에 필요한 플랫폼 기능이 필요합니다. 이 가이드에는 실제로 작동하는 로그인 정보나 연결된 계정이 들어 있지 않습니다.

V1과 V2는 같은 계정 API 키와 같은 잔액을 사용합니다. 과금되는 요청을 설정하기 전에 GET /api/v2/usage로 키를 확인하고, 이 엔드포인트의 응답에서 meta.access.mode 값이 api_key인지 확인하세요. 키가 없거나 인식되지 않으면 공유 IP 체험으로 대체될 수 있습니다. 운영 중인 자동화가 이를 모르는 채로 IP 체험에 의존해서는 안 됩니다.

설정하는 동안에는 워크플로를 비활성화해 두세요. 테스트 추정 요청에도 일반 크레딧이 차감됩니다. 이 가이드는 공개 문서와 V2 규격을 기준으로 검토했습니다. 이번 게시를 위해 어떤 플랫폼에서도 인증된 워크플로를 처음부터 끝까지 실행하지는 않았습니다.

인증과 무료 사용량 확인

Pipedream에서 GenderAPI.io V2 요청 설정하기

계정과 워크플로에 맞는 Twilio SendGrid 이벤트나 일정을 선택하세요. 테스트 연락처 하나를 확인하고 그 안정적인 ID를 유지하며, 보강 단계 전에 빈 이메일 값을 건너뛰세요. 트리거에서 사용할 수 있는 간격은 플랫폼 설정이며, GenderAPI가 보장하는 사항이 아닙니다.
Send any HTTP Request 액션을 추가하고 POST를 선택한 다음 아래 URL을 지정하세요. type = email, value = 연락처 이메일, options.ai_mode = off로 JSON 본문을 구성하세요.
Pipedream의 자격 증명 또는 환경 변수 기능을 사용해 키를 저장하세요. Authorization은 Bearer 뒤에 해당 비밀 값을 붙인 값으로, Content-Type은 application/json으로 설정하세요. 쿼리 문자열에 키를 넣는 기본 제공 인증을 재사용하지 말고, 어떤 단계에서도 키를 출력하지 마세요.
액션이 지원하는 매핑 기능으로 본문을 JSON 객체로 구성하세요. 이스케이프되지 않은 연락처 값을 이어 붙여 원시 JSON을 만들지 마세요. 의도적으로 테스트를 한 번 실행하기 전에 요청 미리보기를 확인하세요.

HTTP 설정	값	용도
`Method`	`POST`	추정 요청을 1건 보냅니다.
`URL`	`https://api.genderapi.io/api/v2/gender`	단일 추정에 사용하는 GenderAPI.io V2 엔드포인트입니다.
`Authorization`	`Bearer YOUR_API_KEY`	플랫폼의 인증 설정이나 헤더 설정에서 이 자리 표시자를 바꾸세요.
`Content-Type`	`application/json`	양식 필드가 아니라 중첩된 options 객체가 들어 있는 객체를 보냅니다.
`options.ai_mode`	`off`	데이터셋만 사용하는 의도적인 첫 테스트입니다. 알 수 없는 결과여도 일반 차감은 1크레딧입니다.

보내기 전에 JSON 본문 확인하기

이 예시는 고정된 입력을 보여 줄 뿐이며, 예상 결과가 아닙니다. 먼저 요청 구조를 확인한 다음, 올바른 JSON 직렬화를 사용해 value를 매핑한 원본 필드로 바꾸세요. 플랫폼의 매핑 표현식을 문자 그대로의 텍스트로 API에 붙여 넣지 마세요.

다른 입력을 보낼 때는 type을 name, email 또는 username으로 설정하고 value에 해당 값을 지정하세요. country는 신뢰할 수 있는 국가 컨텍스트가 있을 때만 추가하세요. 이 필드는 선택 사항이며, 사람이 어느 나라에 거주하는지 조회하는 데 쓰이지 않습니다.

{
  "type": "email",
  "value": "alex@example.com",
  "options": {
    "ai_mode": "off"
  }
}

요청의 모든 필드, 유형, 기본값

업데이트를 켜기 전에 HTTP 단계 확인하기

HTTP 단계가 내보내는 응답을 확인하고 파싱된 본문을 찾으세요. 선택한 액션이 본문을 텍스트로 반환한다면, data와 meta를 읽기 전에 한 번 파싱하세요. 전송 래퍼의 data 필드는 V2 본문의 data 필드와 다릅니다.

시간 초과, 리디렉션, 재시도를 명시적으로 처리하는 코드 기반 워크플로가 필요하다면 아래에 연결된, 테스트를 거친 Node.js 가이드를 사용할 수 있습니다. 일반 액션과 기본 제공 앱은 전송 기본값이 서로 다를 수 있습니다.

identified 결과, 알 수 없는 결과, 실패를 따로 처리하기

대상 시스템의 업데이트를 선택하기 전에 응답 본문을 파싱하세요. 아래 JSON 경로는 V2 응답 본문을 기준으로 합니다. 플랫폼에 따라 본문을 감싸거나 평탄화할 수 있습니다. 의도적으로 실행한 테스트로 실제 반환 구조를 확인하고, 결과를 원본 레코드 ID와 연결해 두세요.

추정 결과는 사람의 정체성이나 본인이 밝힌 성별을 확정하지 않습니다. 본인이 제공한 정보와 분리해 저장하세요. 수용 기준은 자신의 사용 사례를 대표하는 데이터에 근거해 정하고, 데이터셋의 신뢰도와 AI의 신뢰도는 따로 평가하세요.

확인 항목	예상 값 또는 유형	워크플로에서의 판단
`meta.access.mode`	계정을 사용하는 이 워크플로에서는 api_key	값이 ip_trial이면 워크플로를 중지하고 키를 바로잡으세요. IP 체험에서 성공한 응답은 계정 인증을 증명하지 않으며, 이미 IP 체험 크레딧을 사용했을 수 있습니다.
`meta.usage.billing_status`	confirmed 또는 unconfirmed	값이 unconfirmed이면 요청 ID를 보관하고, 재시도하거나 계속 진행하기 전에 차감 내역을 확인(대조)하세요.
`data.result_status / data.gender`	identified와 male 또는 female, unknown과 null	수용한 identified 결과는 추정 데이터를 위한 별도 필드로 보내세요. 알 수 없는 결과는 기본 범주를 지정하지 말고 그대로 유지하세요.
`data.confidence / data.confidence_kind`	0부터 1까지의 숫자 또는 null, 근거 유형 또는 null	observed_frequency와 model_reported는 따로 해석하세요. 둘 다 전반적인 정확도를 보장하지 않습니다.
`data.source / data.sample_count`	dataset, ai 또는 none / 정수 또는 null	추정 결과를 얻은 방법을 저장하세요. AI에는 저장된 표본 수가 없으며, 데이터셋의 표본 수는 제품 정확도를 나타내는 지표가 아닙니다.
`meta.request_id / meta.usage`	요청 참조값 / 사용량 객체	둘 다 워크플로의 레코드 및 결과와 함께 저장하세요. API 키와 불필요한 개인정보는 일반 로그에 남기지 마세요.
`HTTP 실패 / 응답 없음`	Problem Details 또는 완전한 응답 없음	업데이트를 일시 중지하고 오류와 과금 상태를 확인하세요. 시간 초과가 발생했다고 해서 서버가 아무 작업도 하지 않았다는 뜻은 아닙니다.

Twilio SendGrid에서는 해당 레코드만 업데이트하기

트리거에서 받은 연락처 ID를 파싱된 V2 본문과 함께 보관하세요. 아래의 결과 확인을 마친 뒤에는 계획한 SendGrid 사용자 정의 필드만 업데이트하세요. 연락처가 직접 제공한 이름은 그대로 두세요. 이메일 주소에서 추정한 data.name은 추정된 후보일 뿐이며, 확인된 대체 값이 아닙니다.

업데이트를 켜기 전에 identified 결과, 알 수 없는 결과, 오류 분기를 각각 테스트하세요. 가상의 샘플 응답을 사용하면 새 추정 요청을 보내지 않고도 분기 조건을 확인할 수 있습니다. 대상 앱의 업데이트는 위의 확인 결과에 따라야 하며, 관련 없는 필드나 태그를 덮어쓰면 안 됩니다.

재시도와 중복 차감 관리하기

Pipedream은 요금제에 따라 실패한 단계부터 자동으로 재시도한다고 문서화하고 있습니다. 이 설정과 선택한 HTTP 액션의 재시도 동작을 검토하세요. 실패한 보강 단계를 재시도하면 다시 차감될 수 있습니다. 이후 대상 시스템에서 발생한 실패는 저장해 둔 보강 출력을 사용해 복구하세요.

GenderAPI로 보내는 새 요청은 각각 독립된 작업입니다. 전송하기 전에 저장해 둔 원본 ID와 처리 상태를 사용해 워크플로에서 반복된 원본 이벤트의 중복을 제거하세요. 원본 레코드 ID는 서버 측에서 반복 요청을 막아 주는 키가 아닙니다.

성공한 알 수 없는 결과는 차감이 완료된 결과입니다. 시간 초과가 발생하거나 응답이 불완전하면 결과와 차감 여부를 모두 알 수 없을 수 있습니다. 요청 참조값이 있으면 보관하고, 요청을 다시 보내기 전에 차감 내역을 확인하세요. 요청 한도 응답에 Retry-After 헤더가 있으면 그 값을 따르세요.

크레딧과 과금 상태

AI를 사용할 시점 선택하기

forceToGenderize는 이름, 이메일 주소, 사용자 이름에 선택적으로 사용할 수 있습니다. 이 옵션을 켜면 ai_mode를 생략하거나 fallback을 사용하세요. off와 always는 함께 쓸 수 없으며 422를 반환합니다. 최종 차감으로 잔액이 0 아래로 내려가더라도 시작 잔액이 0보다 크면 요청을 시작할 수 있습니다.

별명 모드는 name: null과 함께 성별을 반환할 수 있으며, 알 수 없는 결과를 반환할 수도 있습니다. 일반 AI 폴백도 별명 추정도 정확하거나 null이 아닌 답을 보장하지 않습니다.

요청 옵션	동작	성공한 조회의 크레딧
options.ai_mode: off	데이터셋만 사용합니다.	1(알 수 없는 결과 포함)
options.ai_mode: fallback	먼저 데이터셋을 조회하고, 성별이 반환되지 않으면 일반 AI를 사용합니다. 단일 요청의 기본값입니다.	총 1(AI 폴백 포함)
options.ai_mode: always	AI에 직접 요청합니다.	2
forceToGenderize: true	먼저 데이터셋을 조회한 다음, 실제 이름이 없어도 AI가 개인의 별명이나 별칭을 해석할 수 있게 합니다.	데이터셋에서 결과를 얻으면 1, AI를 사용하면 총 2

처리량을 늘리기 전에 워크플로 검증하기

실제로 직렬화된 JSON, 파싱된 결과 경로, API 키 접근, 확정된 과금을 의도적인 테스트로 확인하세요. 알 수 없는 결과와 실패의 처리는 가능하면 예시 응답으로 테스트하세요.
워크플로의 어느 단계가 재시도하는지, 어떤 고객 필드가 변경되는지 확인하세요. 원본 레코드 ID, 완료된 응답, 요청 참조값을 보관해 두면 나중에 대상 시스템에서 실패가 발생해도 새 요청을 보낼 필요가 없습니다.
먼저 소규모로 통제된 실행만 활성화하고, 병렬 처리를 늘리기 전에 레코드와 크레딧을 확인하세요. GenderAPI의 크레딧과 자동화 플랫폼이 부과하는 작업(task) 또는 오퍼레이션 비용은 별개입니다.
일괄 요청에는 POST /api/v2/gender/batch를 사용하세요. API 키 접근 시 최대 50개 항목, IP 체험에서는 최대 10개 항목을 보낼 수 있습니다. items 배열에는 이름, 이메일 주소, 사용자 이름을 섞을 수 있으며, 항목마다 명시적인 옵션과 고유한 ID를 지정하세요. 모든 결과를 확인하세요. HTTP 200 응답에도 개별 항목의 실패가 포함될 수 있습니다. 기본 제공 커넥터가 일괄 요청을 지원하는지는 따로 확인해야 합니다.

자주 묻는 질문

Pipedream의 기본 제공 GenderAPI.io 액션은 V2를 사용하나요?

2026년 9월 26일에 검토한 공개 컴포넌트는 예전 V1 엔드포인트와 쿼리 문자열 키 인증을 사용합니다. V2 요청에는 명시적인 V2 HTTP 설정을 사용하고, 게시된 컴포넌트의 버전이 바뀌면 다시 확인하세요.

HTTP를 직접 사용하는 예시는 AI를 사용하나요?

첫 번째 요청 본문은 options.ai_mode를 off로 설정합니다. 일반 AI 폴백을 사용하려면 값을 의도적으로 fallback으로 바꾸세요(총 1크레딧). AI를 바로 사용하려면 always로 바꾸세요(2크레딧). forceToGenderize는 먼저 데이터셋을 조회하며, 데이터셋에서 결과가 나오면 1크레딧, AI가 사용되면 총 2크레딧입니다.

알 수 없는 결과는 무료이며, 자동으로 재시도해도 안전한가요?

아니요. 성공한 알 수 없는 결과는 완료된 결과이며 과금됩니다. 재시도는 새로운 작업입니다. 전송 오류가 발생했거나 과금이 확정되지 않았다면, 다시 보낼지 결정하기 전에 반환된 사용량 데이터와 요청 참조값을 확인하세요.

이 워크플로는 연결된 계정으로 실행되었나요?

아니요. 각 플랫폼의 설정 가이드는 2026년 9월 26일에 공개 문서를 기준으로 검토했습니다. GenderAPI.io V2의 요청과 응답 설명은 2026년 9월 27일에 검토했습니다. 이 한국어판을 2026년 9월 30일에 검토한 것은 번역 확인이며, 계정을 사용한 새로운 테스트가 아닙니다. 운영 환경에서 업데이트를 활성화하기 전에, 선택한 액션의 현재 필드, 인증, 본문, 응답, 재시도를 본인 계정으로 테스트하세요.

출처와 문서

한국어판은 2026년 9월 30일에 마지막으로 검토했습니다. 각 플랫폼에 관한 정보는 2026년 9월 26일에 확인한 공개 문서를 바탕으로 합니다. 이 검토는 연결된 계정으로 새로 실행한 테스트가 아닙니다. 현재 설정 방법과 제공 여부는 각 플랫폼의 공식 문서에서 확인하세요.