المطورون
مرجع API
تحقق من الهوية باستخدام جلسة أو مفتاح API واستخدم نقاط نهاية الحساب وعروض الأسعار والمثيلات والفوترة المنفذة.
8 دقيقة قراءة · تم التحديثالمصادقة
المسار الأساسي هو /api/v1. تستخدم طلبات المتصفح ملف تعريف ارتباط الجلسة HttpOnly الذي أُنشئ عند تسجيل الدخول. يمكن للبرامج النصية استخدام Authorization: Bearer متبوعًا بمفتاح API نشط. تتمتع المفاتيح بصلاحيات الحساب الكاملة وتُعرض مرة واحدة عند إنشائها.
تستخدم واجهة المستخدم المحلية مفاتيح gh_demo_. يؤدي إبطال المفتاح فورًا إلى منع الطلبات المُصادق عليها الجديدة التي تستخدمه. لا تضع المفاتيح في عناوين URL أو حزم جانب المتصفح.
GET /api/v1/balance
Authorization: Bearer <your-api-key>
200 OK
{ "currency": "USD", "balanceCents": 50000, "derivedFrom": "ledger_entries" }قواعد الطلب وإعادة المحاولة
أجسام POST وPATCH هي كائنات JSON، مع Content-Type: application/json. أرسل {} للإجراءات التي لا تحتوي على معاملات. تقتصر الأجسام على 32 كيبيبايت من النص. تستخدم الاستجابات Cache-Control: no-store.
يتطلب النشر والتجديد اليدوي والسحب Idempotency-Key من 8 إلى 128 حرفًا. استخدم مفتاحًا جديدًا لعملية مقصودة جديدة وأعد استخدام نفس المفتاح لإعادة محاولتها. لا تعيد استخدامه أبدًا مع جسم مختلف. يتضمن رد الإعادة replayed: true.
تحسب عروض أسعار النسخ سعر الكتالوج الحالي دون حجز السعة. أرسل expectedPriceCents عند النشر؛ في حال عدم التطابق يُعاد 409 حتى يمكن مراجعة السعر مرة أخرى.
POST /api/v1/instances
Content-Type: application/json
Idempotency-Key: <unique-operation-id>
Authorization: Bearer <your-api-key>
{
"sku": "nvidia-rtx-4090",
"gpuCount": 1,
"region": "dal",
"image": "pytorch",
"period": "week",
"options": [],
"sshKeyId": "<saved-key-id>",
"autoRenew": false,
"expectedPriceCents": 11000
}نقاط النهاية المنفذة
جميع موارد الحساب مقيدة بمالكها. نقطة نهاية التوفر عامة وتعرض لقطة الكتالوج، وليست فحصًا مباشرًا للأجهزة.
| الطريقة | المسار بعد /api/v1 | الغرض |
|---|---|---|
| POST | /auth/register · /auth/login | اسم المستخدم + كلمة المرور؛ إنشاء جلسة |
| POST | /auth/recover | اسم المستخدم + رمز غير مستخدم + كلمة مرور جديدة |
| POST | /auth/logout | إبطال جلسة المتصفح الحالية |
| GET | /me · /balance · /ledger | الحساب والرصيد وأحدث 100 إدخالات |
| GET / DELETE | /sessions · /sessions/:id | عرض الجلسات النشطة أو إلغاء إحداها |
| GET | /availability | الكتالوج العام ولقطة المخزون الإقليمي |
| GET / POST | /deposit-quotes | اعرض عروض الأسعار النشطة أو أنشئ واحدًا باستخدام asset + desiredUsdCents |
| POST | /demo/confirm-deposit | معرف عرض الأسعار؛ للتطوير المحلي فقط |
| GET | /deposits · /withdrawals | أحدث 100 سجل لهذا الحساب |
| POST | /withdrawals | الأصل + الوجهة + amountUsdCents؛ قابل للتكرار |
| POST | /instance-quotes | GPU والعدد والمنطقة والصورة والمدة والخيارات |
| GET / POST | /instances | اعرض التخصيصات أو انشر؛ النشر متكرر آمن |
| POST | /instances/:id/start · stop · release · renew | إجراء دورة الحياة؛ التجديد متكرر بدون أثر إضافي |
| PATCH | /instances/:id/auto-renew | اضبط enabled على true أو false |
| GET / POST | /ssh-keys · /api-keys | عرض أو إنشاء مفاتيح الحساب |
| DELETE | /ssh-keys/:id · /api-keys/:id | إلغاء مفتاح |
تعامل مع الأخطاء بشكل صريح
تحتوي الأخطاء على {error, message}: رمز ثابت وشرح مقروء. يشير 400 إلى إدخال غير صالح، و401 إلى مصادقة مفقودة أو غير صالحة، و403 إلى أصل مرفوض، و404 إلى مورد غير معروف أو غير مملوك، و409 إلى تعارض في الرصيد/state/duplicate، و415 إلى نوع محتوى خاطئ.
بالنسبة لعرض سعر إيداع منتهي الصلاحية، أنشئ عرض سعر آخر. بالنسبة لحالة مثيل متغيرة، أعد تحميل المثيل قبل اتخاذ أي إجراء آخر. بعد انقطاع الشبكة، أعد استخدام مفتاح العملية بدلاً من إنشاء رسوم ثانية.