API 문서

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: 가입하기 (v2)
PURPOSE: 무료 계정을 만들고 로그인 비밀번호와 API 토큰을 받아봐. 인증은 필요 없어.

--- API DETAILS ---
Method: POST
URL: https://gender-api.com/v2/sign-up

--- AUTHENTICATION ---
Header: Content-Type: application/json

--- REQUEST PARAMETERS ---

Parameter: email
  Type: string
  Required: REQUIRED
  Description: 가입할 이메일 주소야. 이름이나 성은 입력할 필요 없어.

Parameter: accept_terms
  Type: bool
  Required: REQUIRED
  Description: 반드시 true여야 해. 사용자는 Terms and Conditions 및 개인정보 처리방침에 동의해야 해.

Parameter: newsletter
  Type: bool
  Required: OPTIONAL
  Description: 뉴스레터를 구독해. 기본값은 false야.

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: 계정 언어. en, de, es 중 하나. 기본값은 en.

--- REQUEST EXAMPLES ---

Example 1: 이메일 주소로 가입하기
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true
}

Example 2: 가입하고 뉴스레터를 구독해줘
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true,
    "newsletter": true,
    "locale": "en"
}

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "email": "user@example.com",
    "password": "",
    "api_token": "",
    "free_requests_per_month": 100,
    "status": "awaiting_activation",
    "message": "Account created. Ask the user to click the activation link sent to their email address. The API token below activates automatically once the email is confirmed and can then be used as a Bearer token against the API.",
    "docs_url": "https://gender-api.com/skill.md"
}

--- RESPONSE FIELDS ---

Field: email
  Type: string
  Description: 등록된 이메일 주소.

Field: password
  Type: string
  Description: 웹 대시보드에 로그인할 때 쓰는 임의의 비밀번호야. 이 비밀번호는 한 번만 반환되니까 안전하게 저장해줘. 나중에 “비밀번호를 잊으셨나요?” 절차를 통해 다시 설정할 수 있어.

Field: api_token
  Type: string
  Description: API 베어러 토큰이야. /v2/... 요청에서는 "Authorization: Bearer " 형태로 사용해. 사용자가 이메일을 확인(인증)하면 바로 작동하기 시작해.

Field: free_requests_per_month
  Type: int
  Description: 매달 제공되는 무료 요청 수입니다.

Field: status
  Type: string
  Description: 계정 상태입니다. 이메일 주소가 확인될 때까지는 "awaiting_activation" 상태로 표시돼.

Field: message
  Type: string
  Description: 이메일 주소를 확인하는 다음 단계에 대한 이해하기 쉬운 안내문.

Field: docs_url
  Type: string
  Description: 프롬프트에 바로 사용할 수 있는 AI 구현 지침(skill.md) 링크.

--- IMPLEMENTATION NOTES ---

1. Make sure to replace placeholder values:
   - Replace '' with your actual API key
   - Replace domain placeholders with the actual API domain

2. Handle errors appropriately:
   - Check HTTP status codes
   - Parse error responses
   - Implement retry logic for transient failures

3. Best Practices:
   - Store API keys securely (use environment variables)
   - Implement rate limiting on your side
   - Cache responses when appropriate
   - Use HTTPS for all requests
   - Set appropriate timeout values

4. RECOMMENDED: Implement the Statistics Endpoint
   - The statistics endpoint allows users to monitor their credit usage
   - Users can see how many credits they have used and how many are left
   - This helps prevent unexpected service interruptions
   - API v1: GET /get-stats?key=YOUR_API_KEY
   - API v2: GET /v2/statistic (with Authorization Bearer token)
   - Display remaining credits in your application's UI
   - Consider adding alerts when credits are running low

--- IMPLEMENTATION TEMPLATE ---

// Example implementation in cURL:
curl -X POST \
  'https://gender-api.com/v2/sign-up' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","accept_terms":true}'

--- CREDIT USAGE ---
Required Requests: 0

=== END OF INSTRUCTIONS ===