DOKUMENTACE API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Registrace (v2)
PURPOSE: Vytvořte si účet zdarma a získáte přihlašovací heslo a API token. Není vyžadováno žádné ověření.

--- 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: E-mailová adresa pro registraci. Není potřeba uvádět jméno ani příjmení.

Parameter: accept_terms
  Type: bool
  Required: REQUIRED
  Description: Musí být true. Uživatel musí souhlasit s Obchodními podmínkami a Zásadami ochrany osobních údajů.

Parameter: newsletter
  Type: bool
  Required: OPTIONAL
  Description: Přihlášení k odběru newsletteru. Výchozí hodnota je false.

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Jazyk účtu. Jeden z: en, de, es. Výchozí je en.

--- REQUEST EXAMPLES ---

Example 1: Zaregistrujte se pomocí e-mailové adresy
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true
}

Example 2: Zaregistrujte se a přihlaste se k odběru newsletteru
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: Registrovaná e-mailová adresa.

Field: password
  Type: string
  Description: Náhodné přihlašovací heslo do webového dashboardu. Vrátí se jen jednou, takže si jej bezpečně uložte. Uživatel si jej později může obnovit přes proces „Zapomenuté heslo“.

Field: api_token
  Type: string
  Description: Bearer token pro API. Použijte jej jako „Authorization: Bearer “ pro požadavky na /v2/.... Začne fungovat, jakmile uživatel potvrdí svůj e-mail.

Field: free_requests_per_month
  Type: int
  Description: Počet bezplatných požadavků, které získáte každý měsíc.

Field: status
  Type: string
  Description: Stav účtu. „awaiting_activation“, dokud nebude e-mailová adresa potvrzena.

Field: message
  Type: string
  Description: Srozumitelný návod k dalšímu kroku (potvrzení e-mailové adresy).

Field: docs_url
  Type: string
  Description: Odkaz na instrukce pro implementaci AI připravené k použití (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 ===