تخطَّ إلى المحتوى
مرجع API
مرجع API

إنشاء مفتاح API

أنشئ مفتاح API قياسياً. احفظ المفتاح النصي الواضح الذي تُعيده هذه العملية لأنه يُعرض مرة واحدة فقط.

عرض Markdown

أنشئ مفتاح API قياسياً. احفظ المفتاح النصي الواضح الذي تُعيده هذه العملية لأنه يُعرض مرة واحدة فقط.

نقطة النهاية

POST /api/v1/keys
عنوان URL الأساسي
https://runapi.ai
إصدار API
v1
المصادقة
Authorization: Bearer YOUR_MANAGEMENT_API_KEY
التفويض
يتطلب مفتاح Management API لمسؤول الحساب. يكون مفتاح API القياسي الجديد مملوكاً للمُستدعي.
02

الطلب

نص JSON

أرسل القيم فقط في موقع الطلب المُدرج.

جسم JSON8 حقل
allowed_modelsarray | null
اختياري

قائمة بيضاء اختيارية لمعرّفات النماذج.

credit_limit_centsinteger | null
اختياري

حد إنفاق اختياري بالسنت الأمريكي.

credit_limit_reset_intervalstring | null
اختياري

دورية إعادة تعيين اختيارية لحد إنفاق المفتاح.

القيم المسموح بها: daily, weekly, monthly
credit_limit_windowsobject
اختياري

حدود الإنفاق المتجددة مفتاحها 1h أو 1d أو 7d؛ تحتوي كل قيمة على عدد صحيح موجب limit_cents.

enabledboolean
اختياري

ما إذا كانت الطلبات التي تستخدم هذا المفتاح مقبولة.

القيمة الافتراضية: true
guardrail_idstring
اختياري

معرّف بادئة اختياري للحاجز الأمني يُرفق عند الإنشاء.

namestring
اختياري

اسم مألوف لمفتاح API.

tagsarray
اختياري

سلاسل key:value كاملة (المفتاح 1–32 محرفاً، والقيمة 1–64، دون مسافات بيضاء؛ 20 وسماً كحد أقصى). وسم واحد من usage:developer أو usage:service؛ الافتراضي عند الإنشاء usage:service. بيئة واحدة اختيارية من env:production أو env:staging أو env:dev.

03

استجابة النجاح

HTTP 201

POST /api/v1/keys

JSON 
{
  "allowed_models": [
    "gpt-5.4"
  ],
  "created_at": "2026-07-27T10:00:00.000Z",
  "credit_limit_cents": 1000,
  "credit_limit_reset_interval": "daily",
  "credit_limit_windows": {
    "1d": {
      "limit_cents": 500
    },
    "1h": {
      "limit_cents": 100
    },
    "7d": {
      "limit_cents": 2000
    }
  },
  "enabled": true,
  "guardrail_id": "guardrail_123",
  "id": "token_123",
  "key": "runapi_plaintext_example",
  "last_used_at": null,
  "masked_token": "runapi_abc...wxyz",
  "name": "Production",
  "tags": [
    "usage:service",
    "env:production",
    "dept:ml"
  ]
}
04

استجابة الخطأ (401)

HTTP 401
مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "رسالة خطأ قابلة للقراءة البشرية.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "Authentication required"
}
05

استجابة الخطأ (403)

HTTP 403
مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "رسالة خطأ قابلة للقراءة البشرية.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "Management API key required"
}
06

استجابة الخطأ (403)

HTTP 403
مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "رسالة خطأ قابلة للقراءة البشرية.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "Account admin required"
}
07

استجابة الخطأ (400)

HTTP 400
مخطط الاستجابة
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "رسالة خطأ قابلة للقراءة البشرية.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "ملخص التحقق القابل للقراءة البشرية.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "رسائل التحقق مفتاحها حقل الطلب العام، مع مصفوفة من السلاسل القابلة للقراءة البشرية لكل حقل.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

مثال على الاستجابة

JSON 
{
  "error": "page must be an integer"
}
08

استجابة الخطأ (422)

HTTP 422
مخطط الاستجابة
JSON 
{
  "properties": {
    "error": {
      "description": "ملخص التحقق القابل للقراءة البشرية.",
      "type": "string"
    },
    "errors": {
      "additionalProperties": {
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "description": "رسائل التحقق مفتاحها حقل الطلب العام، مع مصفوفة من السلاسل القابلة للقراءة البشرية لكل حقل.",
      "type": "object"
    }
  },
  "required": [
    "error",
    "errors"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

مثال على الاستجابة

JSON 
{
  "error": "Validation failed",
  "errors": {
    "base": [
      "Validation failed"
    ]
  }
}
09

مثال cURL

CURL 
curl -X POST https://runapi.ai/api/v1/keys \
  -H 'Authorization: Bearer YOUR_MANAGEMENT_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Production","tags":["env:production","dept:ml"],"credit_limit_cents":1000,"credit_limit_reset_interval":"daily","credit_limit_windows":{"1h":{"limit_cents":100},"1d":{"limit_cents":500},"7d":{"limit_cents":2000}},"allowed_models":["gpt-5.4"],"guardrail_id":"guardrail_123"}'