توثيق API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: سجّل (الإصدار 2)
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: يجب أن يكون هذا الخيار مُفعّلًا. لازم المستخدم يوافق على الشروط والأحكام وسياسة الخصوصية.

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: رمز الحامل (Bearer Token) الخاص بالـ API. استخدمه بهذا الشكل: "Authorization: Bearer " لطلبات /v2/... يبدأ بالعمل بمجرد ما يؤكد المستخدم بريده الإلكتروني.

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: رابط إلى تعليمات تنفيذ الذكاء الاصطناعي الجاهزة للاستخدام (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 ===