دليل التكامل · API
تحديث 2026-10-22
استدعِ الأدوات عبر HTTPS بمفتاح شخصي. نفّذ الأمثلة بالترتيب لفصل الصوت الغنائي من MP3. اقرأ المعلمات وحدود الإدخال قبل تغيير الأداة.
يتطلب Bash وcurl 7.76+ وjq. نفّذ الخطوات في الطرفية نفسها.
01الإعداد والمصادقة
أنشئ مفتاح قراءة وتنفيذ وأرسل Authorization: Bearer. لا تحتاج إلى Cookie تسجيل الدخول أو CSRF أو تحديث جلسة المتصفح.
تسمح القوائم الفارغة بجميع الأدوات والعناوين؛ وتظل سياسة الحساب مطبقة. الميزانيات حسب UTC. يحتفظ النقل المنقطع بحصته المصرح بها. يرث المفتاح الجديد الصلاحيات وتاريخ الانتهاء. حدّث البرامج خلال فترة الانتقال التي لا تتجاوز خمس دقائق.
إنشاء مفتاح →jq() { command jq "$@" | tr -d '\r'; }
read -rsp 'TELKNET_API_KEY: ' TELKNET_API_KEY; printf '\n'
export TELKNET_API_KEY
BASE="${TELKNET_BASE_URL:-https://telknet.cc}"
TOOL="${TELKNET_TOOL:-music-vocal-split}"
FILE="${TELKNET_FILE:-sample.mp3}"
curl --connect-timeout 10 --max-time 60 --fail-with-body "$BASE/api/v1/credits/balance" \
-H "Authorization: Bearer $TELKNET_API_KEY"02رفع ملف
اطلب رابط رفع موقّعًا ثم أرسل الملف الأصلي عبر PUT. استخدم عدد البايتات الحقيقي ونفس Content-Type.
curl --connect-timeout 10 --max-time 60 --fail-with-body "$BASE/api/v1/tools/$TOOL/upload" \
-H "Authorization: Bearer $TELKNET_API_KEY" \
-H 'Content-Type: application/json' \
-d "$(jq -n --arg filename "$(basename "$FILE")" \
--argjson size "$(wc -c < "$FILE")" \
'{filename:$filename,content_type:"audio/mpeg",file_size:$size}')" \
-o upload.json || { cat upload.json >&2; exit 1; }
curl --connect-timeout 10 --max-time 1800 --fail-with-body --request PUT \
-H 'Content-Type: audio/mpeg' --upload-file "$FILE" \
"$(jq -r '.data.upload_url' upload.json)"عادةً يدوم الرابط 15 دقيقة. لا ترسل مفتاح API مع PUT. المثال يستخدم PUT واحدًا؛ مع multipart_supported=true ارفع parts ثم استدعِ upload/multipart/complete أو abort عند الفشل.
03تأكيد السعر والإرسال
اقرأ السعر الأساسي للأداة أو النموذج وأرسله كما هو في pricing ثم احفظ task_id. تتبع الكمية والمعالجة المسبقة تسعير الأداة؛ ويتطلب تدريب RVC تحليلًا وعرض تدريب أولًا.
printf '{}' > params.json
curl --connect-timeout 10 --max-time 60 --fail-with-body "$BASE/api/v1/tools/$TOOL/quote" \
-H "Authorization: Bearer $TELKNET_API_KEY" \
-H 'Content-Type: application/json' \
-d "$(jq -n --slurpfile params params.json '{params:$params[0]}')" \
-o quote.json || { cat quote.json >&2; exit 1; }
jq -n --arg tool "$TOOL" --arg key "$(jq -r '.data.s3_key' upload.json)" \
--slurpfile params params.json --slurpfile quote quote.json \
'{tool_id:$tool,file_key:$key,params:$params[0],pricing:$quote[0].data}' > request.json
REQUEST_KEY="$(date +%s)-$(od -An -N16 -tx1 /dev/urandom | tr -d ' \n')"
printf '%s' "$REQUEST_KEY" > request-key.txt
curl --connect-timeout 10 --max-time 60 --fail-with-body "$BASE/api/v1/tools/$TOOL/tasks" \
-H "Authorization: Bearer $TELKNET_API_KEY" \
-H "Idempotency-Key: $REQUEST_KEY" \
-H 'Content-Type: application/json' --data-binary @request.json -o task.json || { cat task.json >&2; exit 1; }
TASK=$(jq -r '.data.task_id' task.json)عرض السعر لا يحجز الرصيد. عند 409 PRICE_CHANGED اقرأ السعر الجديد وأكده. يتطلب توليد الموسيقى والغناء المرجعي معلمات النماذج المختارة.
احتفظ بملفَي request-key.txt وrequest.json. الحساب نفسه مع Idempotency-Key والمحتوى المطابق يعيد المهمة الأصلية. استخدم مفتاحًا جديدًا للمهمة الجديدة، وتحقق من الإرسال غير المحسوم أولًا.
04متابعة تقدم المهمة
استعلم كل 3 ثوانٍ. نزّل عند completed؛ الحالات failed وtimeout وcancelled نهائية. يتوقف الانتظار بعد ساعتين دون إلغاء المهمة.
deadline=$((SECONDS + 7200))
while (( SECONDS < deadline )); do
curl --connect-timeout 10 --max-time 60 --fail-with-body "$BASE/api/v1/tasks/$TASK" \
-H "Authorization: Bearer $TELKNET_API_KEY" -o status.json || { cat status.json >&2; exit 1; }
status=$(jq -r '.data.status' status.json)
case "$status" in
completed) break ;;
failed|timeout|cancelled) cat status.json >&2; exit 1 ;;
pending|processing) sleep 3 ;;
*) cat status.json >&2; exit 1 ;;
esac
done
test "$(jq -r '.data.status' status.json)" = completed05تنزيل النتائج
رمّز s3_key من output_files للرابط واستخدمه بوصفه fileId. ينقل proxy=true الأصل من نفس المصدر مع التحقق من الملكية.
mkdir -p results
jq -r '.data.output_files | to_entries[] | .key' status.json | while read -r INDEX; do
FILE_ID=$(jq -r --argjson i "$INDEX" '.data.output_files[$i].s3_key | @uri' status.json)
NAME=$(basename "$(jq -r --argjson i "$INDEX" '.data.output_files[$i].name' status.json)")
curl --connect-timeout 10 --max-time 7200 --fail-with-body "$BASE/api/v1/tasks/$TASK/files/$FILE_ID?proxy=true" \
-H "Authorization: Bearer $TELKNET_API_KEY" \
--output "results/$INDEX-$NAME.part" || exit 1
EXPECTED=$(jq -r --argjson i "$INDEX" '.data.output_files[$i].size_bytes' status.json)
test "$(wc -c < "results/$INDEX-$NAME.part")" -eq "$EXPECTED" || exit 1
mv "results/$INDEX-$NAME.part" "results/$INDEX-$NAME"
doneتعيد طلبات Bearer إلى /api/v1/tasks/{taskId}/download الملف الأصلي أو ZIP مباشرة. تسري مدة الاحتفاظ، ولا يُمرر مفتاح API إلى مخزن الكائنات.
الأخطاء والاسترداد
اقرأ حالة HTTP وقيم error.code وmessage وdetails الأصلية. لا تعتمد على نص الرسالة فقط ولا تحفظ استجابة خطأ كملف نتيجة.
| 400 | تحقق من الملف والمعلمات وJSON. |
| 401 | المفتاح مفقود أو غير صالح أو منتهٍ أو ملغى. |
| 402 | الرصيد غير كافٍ؛ راجع الرصيد. |
| 403 | صلاحية قراءة فقط أو لا يوجد وصول. |
| 404 | المورد غير موجود أو يخص حسابًا آخر. |
| 409 | تغير السعر أو حالة المهمة؛ اقرأ رمز الخطأ. |
| 413 | يتجاوز الملف حد الأداة. |
| 429 | طلبات كثيرة؛ انتظر Retry-After. |
| 503 | صيانة أو عطل مؤقت؛ احتفظ بالخطأ وتحقق لاحقًا. |
عند 429 انتظر Retry-After أو استخدم تأخيرًا تصاعديًا محدودًا. أعد فقط عمليات القراءة الآمنة. عند انتهاء مهلة POST للرفع أو الإرسال تحقق أولًا من النتيجة الأصلية ولا تُنشئ مهام مكررة.
{
"ok": false,
"error": {
"code": "API_KEY_SCOPE",
"message": "لا يسمح مفتاح API بهذه العملية.",
"details": []
}
}HTTP_CODE=$(curl --connect-timeout 10 --max-time 60 --silent --show-error \
-H "Authorization: Bearer $TELKNET_API_KEY" \
--output response.json --dump-header response.headers --write-out '%{http_code}' \
"$BASE/api/v1/tasks/$TASK")
if [[ "$HTTP_CODE" != 2* ]]; then
cat response.json >&2
if [[ "$HTTP_CODE" == 429 ]]; then
awk 'tolower($1)=="retry-after:" {print $2}' response.headers
fi
exit 1
fiاحتفظ بـ task_id في task.json وتابع من الاستعلام. راجع الإرسالات الحديثة في القائمة، واستدعِ cancel فقط إذا أردت إيقاف المهمة.
مرجع API
تستخدم المسارات /api/v1 على نفس الموقع. تصل المفاتيح إلى مواردك فقط، ولا تدير الحساب أو تُنشئ مفاتيح أو تصل للإدارة والاستدعاءات الداخلية.
| GET | /api/v1/tools | دليل الأدوات |
| GET | /api/v1/tools/{toolId} | المعلمات وحدود الإدخال |
| GET | /api/v1/credits/balance | رصيد الحساب |
| POST | /api/v1/tools/{toolId}/quote | السعر الحالي |
| POST | /api/v1/tools/{toolId}/upload | رفع ملف |
| POST | /api/v1/tools/{toolId}/tasks | تأكيد السعر والإرسال |
| GET | /api/v1/tasks/{taskId} | متابعة تقدم المهمة |
| GET | /api/v1/tasks | قائمة مهامك |
| GET | /api/v1/tasks/{taskId}/files/{fileId}?proxy=true | تنزيل النتائج |
| POST | /api/v1/tasks/{taskId}/cancel | إلغاء مهمتك |
تعمل midi-converter وmidi-lyrics في المتصفح دون API للرفع أو التنفيذ على الخادم. تحدد تفاصيل الأدوات الأخرى الحالة والصيغ والحجم والمعلمات.