تتيح لك واجهة PicassoIA API تشغيل نماذج الصور والفيديو من PicassoIA انطلاقًا من شيفرتك البرمجية:

1. تُنشئ تنبؤًا لنموذج ما.
2. تستعلم عن التنبؤ دوريًا حتى ينتهي.
3. تقرأ عناوين URL الخاصة بالمخرجات.

• عنوان URL الأساسي: https://api.picassoia.com/v1
• التنسيق: طلبات واستجابات بصيغة JSON، بترميز UTF-8.
• السعر: تنبؤات API مجانية حاليًا، فهي لا تستهلك أي أرصدة.
• من يمكنه استخدامها: الحسابات المشتركة في خطة Infinite.

المحتويات

• المصادقة
• البدء السريع
• النماذج
• نقاط النهاية
• كائن التنبؤ
• الاستعلام الدوري وتقدير الوقت (ETA)
• الإلغاء
• الأخطاء
• الحدود

المصادقة

يتطلب كل طلب مفتاح API في الترويسة Authorization:

Authorization: Bearer pia_sk_…

• إنشاء مفتاح. أنشئ المفاتيح على picassoia.com، في قسم مفاتيح API ضمن حسابك.
  • يُعرض المفتاح كاملًا مرة واحدة فقط، عند إنشائه. احفظه في مكان آمن.
  • يمكن أن يحتوي الحساب على مفتاحين كحد أقصى في الوقت نفسه. لإفساح المجال لمفتاح جديد، أبطِل أحدهما.
• إبطال مفتاح. يتوقف المفتاح المُبطَل عن العمل فورًا.
• احتفظ بالمفاتيح على الخادم. يستطيع أي شخص يملك مفتاحًا تشغيل تنبؤات على حسابك، لذا لا تضع مفتاحًا أبدًا في صفحة ويب أو في تطبيق للهاتف المحمول. لا ترسل الواجهة أي ترويسات CORS، لذا لا يمكن للمتصفحات استدعاؤها مباشرة.
• تغيير الخطة. تبقى المفاتيح قائمة إذا تغيّرت خطتك. ومن دون خطة Infinite، تُرجع طلبات إنشاء التنبؤات الاستجابة 403 plan_required. أما قراءة تنبؤاتك وسردها وإلغاؤها فتظل متاحة.

البدء السريع

1. أنشئ تنبؤًا:

curl -s -X POST https://api.picassoia.com/v1/models/picassoia/picassoia-image/predictions \
  -H "Authorization: Bearer $PICASSOIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "a lighthouse at sunset, oil painting", "aspect_ratio": "16:9"}}'

الاستجابة (201 Created) هي تنبؤ في الحالة starting:

{
  "id": "api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
  "model": "picassoia/picassoia-image",
  "input": {
    "prompt": "a lighthouse at sunset, oil painting",
    "aspect_ratio": "16:9",
    "num_outputs": 1,
    "output_format": "jpg",
    "output_quality": 80
  },
  "output": null,
  "error": null,
  "status": "starting",
  "created_at": "2026-10-01T09:30:00.000Z",
  "started_at": null,
  "completed_at": null,
  "metrics": { "predict_time": null },
  "urls": {
    "get": "https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
    "cancel": "https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60/cancel"
  },
  "eta": { "seconds": 12, "next_poll_in_seconds": 6 }
}

2. استعلم عنه دوريًا (انتظر eta.next_poll_in_seconds بين الاستدعاءات) حتى تصبح قيمة status هي succeeded أو failed أو canceled:

curl -s https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60 \
  -H "Authorization: Bearer $PICASSOIA_API_KEY"

3. اقرأ المخرجات:

{
  "id": "api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
  "status": "succeeded",
  "output": ["https://…/lighthouse.jpg"],
  "metrics": { "predict_time": 6.4 },
  "eta": null
}

(حُذفت الحقول الأخرى هنا.)

Node.js (باستخدام fetch)

const API = 'https://api.picassoia.com/v1'
const headers = {
  Authorization: `Bearer ${process.env.PICASSOIA_API_KEY}`,
  'Content-Type': 'application/json',
}
const sleep = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000))

async function run(model, input) {
  const created = await fetch(`${API}/models/${model}/predictions`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ input }),
  })
  let prediction = await created.json()
  if (!created.ok) throw new Error(`${prediction.code}: ${prediction.detail}`)

  while (!['succeeded', 'failed', 'canceled'].includes(prediction.status)) {
    await sleep(prediction.eta?.next_poll_in_seconds ?? 2)
    prediction = await (await fetch(prediction.urls.get, { headers })).json()
  }
  if (prediction.status !== 'succeeded') throw new Error(prediction.error ?? prediction.status)
  return prediction.output
}

const video = await run('picassoia/seedance-2.5-lite', {
  prompt: 'a paper boat sailing down a rainy street',
  duration: 5,
})
console.log(video) // "https://…/video.mp4"

Python (باستخدام requests)

import os, time, requests

API = "https://api.picassoia.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PICASSOIA_API_KEY']}"}

def run(model, input):
    response = requests.post(f"{API}/models/{model}/predictions", json={"input": input}, headers=HEADERS)
    prediction = response.json()
    if not response.ok:
        raise RuntimeError(f"{prediction['code']}: {prediction['detail']}")
    while prediction["status"] not in ("succeeded", "failed", "canceled"):
        time.sleep((prediction.get("eta") or {}).get("next_poll_in_seconds", 2))
        prediction = requests.get(prediction["urls"]["get"], headers=HEADERS).json()
    if prediction["status"] != "succeeded":
        raise RuntimeError(prediction["error"] or prediction["status"])
    return prediction["output"]

images = run("picassoia/picassoia-image-editor-pro", {
    "prompt": "put the cat from image 1 on the sofa from image 2",
    "images": ["https://example.com/cat.png", "https://example.com/sofa.jpg"],
})
print(images)  # ["https://…/result.webp"]

النماذج

يُقدَّم المخطط الدقيق لكل نموذج أيضًا بصيغة JSON Schema: إذ يُرجع GET /v1/models/{owner}/{name} كلًّا من input_schema (بكل حقل وحدوده وقيمه الافتراضية) وoutput_schema.

الصور كمدخلات. تقبل حقول الصور أيًّا من نوعَي القيم التاليين:

• عنوان URL من نوع https يمكن الوصول إليه للعموم؛
• عنوان data URL: data:image/png;base64,…، وكذلك image/jpeg أو image/webp، بحجم أقصاه 5 ميغابايت لكل منها.

يجب أن تكون الصور بصيغة PNG أو JPEG أو WebP. تحتفظ PicassoIA بنسختها الخاصة من كل صورة، لذا يعرض الحقل input في التنبؤ عنوان URL لتلك النسخة. استخدم عناوين URL لأي صورة يتجاوز حجمها بضع مئات من الكيلوبايت: إذ إن الحد الأقصى لجسم الطلب بأكمله هو 10 ميغابايت.

تُرفض الحقول غير المعروفة، حتى لا يؤدي خطأ إملائي إلى الرجوع بصمت إلى قيمة افتراضية. وتكون الاستجابة 422 invalid_input.

picassoia/picassoia-image

المخرجات: قائمة بعنوان URL واحد أو عنوانين للصور.

picassoia/picassoia-image-editor-pro

المخرجات: قائمة بعنوان URL واحد أو عنوانين للصور.

picassoia/picassoia-video

المخرجات: عنوان URL واحد لملف MP4 (سلسلة نصية).

picassoia/seedance-2.5-lite

المخرجات: عنوان URL واحد لملف MP4 (سلسلة نصية).

نقاط النهاية

كائن النموذج

{
  "id": "picassoia/seedance-2.5-lite",
  "owner": "picassoia",
  "name": "seedance-2.5-lite",
  "title": "Seedance 2.5 Lite",
  "description": "Text or image to video with synchronized audio: …",
  "input_schema": { "type": "object", "properties": { "…": {} }, "required": ["prompt"], "additionalProperties": false },
  "output_schema": { "type": "string", "format": "uri" }
}

إنشاء تنبؤ

أرسل POST /v1/models/{owner}/{name}/predictions مع جسم الطلب { "input": { … } }.

• تستجيب الواجهة بمجرد أن يقبل النموذج المهمة، عادةً في غضون ثوانٍ، بتنبؤ في الحالة starting. ولا تنتظر النتيجة أبدًا.
• إذا فشل التنبؤ على الفور، تظل الاستجابة 201، مع تنبؤ في الحالة failed وحقل error الخاص به. يحدث هذا مثلًا عندما يرفض مرشّح الأمان المدخلات.
• إذا لم يُنشأ أي تنبؤ، تكون الاستجابة خطأً: مدخلات غير صالحة، أو خطة غير مؤهلة، أو كثرة التنبؤات قيد التنفيذ، أو عدم توفر الخدمة.

سرد التنبؤات

يُرجع GET /v1/predictions تنبؤات API الخاصة بك، بواقع 50 تنبؤًا في كل صفحة، الأحدث أولًا، عبر جميع مفاتيحك.

• الحقل next هو عنوان URL للصفحة التالية (…/v1/predictions?cursor=…)، أو null في الصفحة الأخيرة.
• الحقل previous قيمته null دائمًا.
• لا تُدرج التنبؤات التي حذفتها على picassoia.com.

يمكن الاطلاع على التنبؤ عبر أي من مفاتيحك، ولا يراه أي شخص آخر أبدًا.

كائن التنبؤ

الحالات.

التمييز بين starting وprocessing هو تقدير مبني على الموضع في قائمة الانتظار عند الإنشاء. ويكون التنبؤ الجديد دائمًا في الحالة starting. أما الحالات الثلاث الأخيرة فهي نهائية: التنبؤ الذي يصل إلى إحداها لا يتغير بعد ذلك أبدًا.

أخطاء التنبؤ الفاشل. تكون قيمة error في التنبؤ الفاشل إحدى الرسائل التالية:

• رفض مرشّح الأمان المدخلات أو المخرجات. وتنتهي الرسالة بالعبارة (SAFETY_CHECKER_PICASSO_FILTER_S4).
• The prediction failed. You can try again.
• The prediction timed out. You can try again. لم يكتمل التنبؤ في غضون 3 ساعات.

المخرجات. تستضيف PicassoIA عناوين URL للمخرجات. نزّل الملفات التي تريد الاحتفاظ بها.

الاستعلام الدوري وتقدير الوقت (ETA)

يخبرك eta.next_poll_in_seconds بالوقت الذي يستحق فيه إجراء الاستعلام التالي:

1. عند منتصف الوقت المقدَّر.
2. عند بلوغ الوقت المقدَّر.
3. ثم كل ثانيتين.

مثال بوقت مقدَّر قدره 10 ثوانٍ: استعلم بعد 5 ثوانٍ، ثم بعد 10 ثوانٍ، ثم كل ثانيتين. الاستعلام بوتيرة أسرع لن يمنحك النتيجة في وقت أبكر.

الإلغاء

عند إرسال POST /v1/predictions/{id}/cancel:

يُفسح التنبؤ المُلغى مكانه فورًا ضمن حد 5 تنبؤات قيد التنفيذ المسموح به لك.

الأخطاء

الأخطاء عبارة عن تفاصيل مشكلات (problem details) بصيغة JSON، مع إضافة code ثابت مخصص للبرامج:

{
  "title": "Too many predictions in progress",
  "detail": "This account can have up to 5 predictions queued or running at once, shared by its API keys and MCP connections, and 5 are. Wait for one to finish and try again.",
  "status": 429,
  "code": "concurrency_limit",
  "retry_after": 10,
  "limit": 5,
  "running": 5
}

invalid_fields. تسرد الاستجابة 422 كل حقل به خطأ:

{
  "title": "Input validation failed",
  "status": 422,
  "code": "invalid_input",
  "detail": "input.duration: At 720p the longest clip is 10 seconds.",
  "invalid_fields": [
    { "type": "invalid_value", "field": "input.duration", "description": "At 720p the longest clip is 10 seconds." }
  ]
}

الحدود