DOCUMENTATION DE L’API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Inscris-toi (v2)
PURPOSE: Crée un compte gratuit et reçois un mot de passe de connexion ainsi qu’un jeton API. Aucune authentification requise.

--- 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: L’adresse e-mail pour t’inscrire. Aucun prénom ni nom de famille n’est requis.

Parameter: accept_terms
  Type: bool
  Required: REQUIRED
  Description: Doit être vrai. Tu dois accepter les Conditions générales et la Politique de confidentialité.

Parameter: newsletter
  Type: bool
  Required: OPTIONAL
  Description: Abonne-toi à la newsletter. Valeur par défaut : false.

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Langue du compte. Au choix : en, de, es. Par défaut : en.

--- REQUEST EXAMPLES ---

Example 1: Inscris-toi avec une adresse e-mail
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true
}

Example 2: Inscris-toi et abonne-toi à la newsletter
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: L’adresse e-mail enregistrée.

Field: password
  Type: string
  Description: Un mot de passe de connexion aléatoire pour le tableau de bord web. Il n’est renvoyé qu’une seule fois : conserve-le en lieu sûr. L’utilisateur pourra le réinitialiser plus tard via le processus « mot de passe oublié ».

Field: api_token
  Type: string
  Description: Le token Bearer de l’API. Utilise-le comme « Authorization: Bearer  » pour les requêtes /v2/.... Il commence à fonctionner une fois que l’utilisateur a confirmé son e-mail.

Field: free_requests_per_month
  Type: int
  Description: Le nombre de requêtes gratuites accordées par mois.

Field: status
  Type: string
  Description: Le statut du compte. « awaiting_activation » tant que l’adresse e-mail n’est pas confirmée.

Field: message
  Type: string
  Description: Des instructions claires sur la prochaine étape (confirmer ton adresse e-mail).

Field: docs_url
  Type: string
  Description: Lien vers les instructions d’implémentation IA prêtes à l’emploi (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 ===