يستخدم PicassoIA Reference To Video معرّف النموذج picassoia/picassoia-reference-to-video. تحويل المراجع إلى فيديو مع الصوت ومقاطع مدتها من 1 إلى 15 ثانية ودقة 480p أو 720p.
استدعاء API
أرسل الطلبات إلى https://api.picassoia.com/v1/models/picassoia/picassoia-reference-to-video/predictions بجسم JSON يتوافق فيه الكائن input مع المعاملات أدناه.
الإعداد
احتفظ بمفتاح API على خادمك، في متغير بيئة، وأرسله في ترويسة Authorization مع كل طلب.
export PICASSOIA_API_KEY="pia_sk_…"معاملات الطلب
promptstringمطلوب- القيمة الافتراضيةلا يوجد
- ما ينبغي أن تُظهره المخرجات. عدد الأحرف: حتى 8000.
imagesarray- القيمة الافتراضيةلا يوجد
- الصور المراد تعديلها أو دمجها. استخدم image 1 وimage 2 وهكذا للإشارة إليها في الموجّه. عدد الصور من 1 إلى 9. يجب إرسال حقل واحد على الأقل من هذه الحقول: images أو video. صورة بصيغة PNG أو JPEG أو WebP، كعنوان URL عام من نوع https أو كعنوان data URL بحجم أقصاه 5 ميغابايت.
videostring- القيمة الافتراضيةلا يوجد
- الفيديو الذي تنطلق منه. يجب إرسال حقل واحد على الأقل من هذه الحقول: images أو video. فيديو بصيغة MP4 أو MOV أو WebM بحجم أقصاه 50 ميغابايت، كعنوان URL عام من نوع https.
audiostring- القيمة الافتراضيةلا يوجد
- الصوت الذي تنطلق منه. ملف بصيغة MP3 أو WAV أو M4A أو AAC أو OGG أو FLAC بحجم أقصاه 20 ميغابايت، كعنوان URL عام من نوع https.
resolutionstring- القيمة الافتراضية
"480p" - حجم المخرجات. الخيارات: 480p و720p.
durationinteger- القيمة الافتراضية
5 - مدة المقطع بالثواني. من 1 إلى 15.
aspect_ratiostring- القيمة الافتراضية
"match_input_image" / "16:9" - شكل المخرجات. وحيث يتوفر الخيار match_input_image، فإنه يحافظ على نِسب أبعاد الصورة المدخلة، أو الصورة الأولى عند وجود عدة صور. الخيارات: match_input_image و16:9 و9:16 و4:3 و3:4 و3:2 و2:3 و1:1. إذا لم ترسله: match_input_image عند إرسال video، و16:9 عند عدم إرساله.
video_strengthstring- القيمة الافتراضية
"high" - مدى اتباع المقطع للفيديو المرجعي. الخيارات: high وmedium وlow. يتطلب الحقل video.
save_audioboolean- القيمة الافتراضية
true - الاحتفاظ بالمسار الصوتي المُولَّد.
seedinteger- القيمة الافتراضيةلا يوجد
- اضبطها لإعادة إنتاج نتيجة ما، أو احذفها لتكون عشوائية.
enhance_promptboolean- القيمة الافتراضية
true - تعيد Picasso IA صياغة موجّهك للحصول على نتيجة أفضل. ويبقى موجّهك الأصلي في المدخلات.
الأوضاع
يتحدد الوضع بالملفات التي ترسلها مع الموجّه، إن وُجدت. وتستخدم جميع الأوضاع نقطة النهاية نفسها.
مثال على الطلب
تحويل المراجع إلى فيديو
curl -s -X POST https://api.picassoia.com/v1/models/picassoia/picassoia-reference-to-video/predictions \
-H "Authorization: Bearer $PICASSOIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"prompt":"Image 1, the woman with red hair, walks into Image 2, the cafe, and sits by the window. Soft cafe ambience.","images":["https://example.com/woman.jpg","https://example.com/cafe.jpg"]}}'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))
const input = {
prompt: "Image 1, the woman with red hair, walks into Image 2, the cafe, and sits by the window. Soft cafe ambience.",
images: [
"https://example.com/woman.jpg",
"https://example.com/cafe.jpg"
]
}
const created = await fetch(`${API}/models/picassoia/picassoia-reference-to-video/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)
console.log(prediction.output)import os, time, requests
API = "https://api.picassoia.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PICASSOIA_API_KEY']}"}
payload = {"input": {
"prompt": "Image 1, the woman with red hair, walks into Image 2, the cafe, and sits by the window. Soft cafe ambience.",
"images": [
"https://example.com/woman.jpg",
"https://example.com/cafe.jpg",
],
}}
response = requests.post(f"{API}/models/picassoia/picassoia-reference-to-video/predictions", json=payload, 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"])
print(prediction["output"])المصادقة
يحتاج كل طلب إلى مفتاح API في ترويسة Authorization، كرمز Bearer. أنشئ المفاتيح من حسابك؛ يُعرض المفتاح كاملًا مرة واحدة.
Authorization: Bearer $PICASSOIA_API_KEYقائمة الانتظار والاستعلام الدوري
يمر كل تنبؤ بثلاث خطوات: أنشئه، ثم استعلم عنه دوريًا حتى ينتهي، ثم اقرأ النتيجة.
الإرسال
تستجيب الواجهة بالرمز 201، عادةً في غضون ثوانٍ، بالتنبؤ في الحالة starting، مع تقدير للوقت في eta والعنوان الذي تستعلم عنه في urls.get. وإذا فشل التنبؤ على الفور، كأن يرفض مرشّح الأمان المدخلات، تظل الاستجابة 201، مع التنبؤ في الحالة failed والخطأ الخاص به.
curl -s -X POST https://api.picassoia.com/v1/models/picassoia/picassoia-reference-to-video/predictions \
-H "Authorization: Bearer $PICASSOIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"prompt":"Image 1, the woman with red hair, walks into Image 2, the cafe, and sits by the window. Soft cafe ambience.","images":["https://example.com/woman.jpg","https://example.com/cafe.jpg"]}}'const API = 'https://api.picassoia.com/v1'
const headers = {
Authorization: `Bearer ${process.env.PICASSOIA_API_KEY}`,
'Content-Type': 'application/json',
}
const input = {
prompt: "Image 1, the woman with red hair, walks into Image 2, the cafe, and sits by the window. Soft cafe ambience.",
images: [
"https://example.com/woman.jpg",
"https://example.com/cafe.jpg"
]
}
const created = await fetch(`${API}/models/picassoia/picassoia-reference-to-video/predictions`, {
method: 'POST',
headers,
body: JSON.stringify({ input }),
})
let prediction = await created.json()
if (!created.ok) throw new Error(`${prediction.code}: ${prediction.detail}`)
console.log(prediction.id, prediction.status) // api_…, startingimport os, requests
API = "https://api.picassoia.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PICASSOIA_API_KEY']}"}
payload = {"input": {
"prompt": "Image 1, the woman with red hair, walks into Image 2, the cafe, and sits by the window. Soft cafe ambience.",
"images": [
"https://example.com/woman.jpg",
"https://example.com/cafe.jpg",
],
}}
response = requests.post(f"{API}/models/picassoia/picassoia-reference-to-video/predictions", json=payload, headers=HEADERS)
prediction = response.json()
if not response.ok:
raise RuntimeError(f"{prediction['code']}: {prediction['detail']}")
print(prediction["id"], prediction["status"]) # api_…, starting{
"id": "api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
"model": "picassoia/picassoia-reference-to-video",
"input": {
"prompt": "Image 1, the woman with red hair, walks into Image 2, the cafe, and sits by the window. Soft cafe ambience.",
"images": [
"https://example.com/woman.jpg",
"https://example.com/cafe.jpg"
],
"resolution": "480p",
"duration": 5,
"aspect_ratio": "16:9",
"save_audio": true,
"enhance_prompt": true
},
"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": 60,
"next_poll_in_seconds": 30
}
}الاستعلام
استعلم عن urls.get مجددًا بعد eta.next_poll_in_seconds: عند منتصف الوقت المقدَّر، ثم عند بلوغه، ثم كل ثانيتين.
# Repeat after eta.next_poll_in_seconds until status is
# succeeded, failed or canceled.
curl -s https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60 \
-H "Authorization: Bearer $PICASSOIA_API_KEY"const sleep = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000))
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()
}import time
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(){
"id": "api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
"status": "processing",
"output": null,
"eta": {
"seconds": 30,
"next_poll_in_seconds": 30
}
}النتيجة
عندما تكون قيمة status هي succeeded، يحتوي output على النتيجة. ويحمل التنبؤ الفاشل سببه في error، أما التنبؤ المُلغى فقد أُوقف قبل أن ينتهي. وهذه الحالات الثلاث نهائية.
# The last poll holds the result: "output" when "status" is succeeded,
# "error" when it is failed. With jq, just those three fields:
curl -s https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60 \
-H "Authorization: Bearer $PICASSOIA_API_KEY" | jq '.status, .output, .error'if (prediction.status !== 'succeeded') throw new Error(prediction.error ?? prediction.status)
console.log(prediction.output)if prediction["status"] != "succeeded":
raise RuntimeError(prediction["error"] or prediction["status"])
print(prediction["output"]){
"id": "api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
"status": "succeeded",
"output": "https://…/output.mp4",
"error": null,
"completed_at": "2026-10-01T09:30:54.000Z",
"metrics": {
"predict_time": 52.8
},
"eta": null
}الإلغاء
يوقف الطلب POST urls.cancel أي تنبؤ لا يزال في قائمة الانتظار (لأي نموذج) أو أي صورة لا تزال قيد التوليد؛ أما الفيديو الذي بدأ توليده بالفعل فتكون الاستجابة له 409 not_cancelable.
المعرّفات والأوقات وعناوين URL في هذه الاستجابات مجرد أمثلة: ستحمل استجاباتك قيمها الخاصة.
المخرجات
عندما ينجح التنبؤ، تكون قيمة output عنوان URL لفيديو MP4.
الأخطاء والحدود
الأخطاء عبارة عن تفاصيل مشكلات (problem details) بصيغة JSON مع code ثابت، والاستجابة 422 تذكر كل حقل به خطأ.
الحدود
- التنبؤات في قائمة الانتظار أو قيد التشغيل في الوقت نفسه: 5 لكل حساب
- جسم الطلب حتى 10 ميغابايت؛ والصور بصيغة data URL حتى 5 ميغابايت لكل منها
- عدد أحرف الموجّه: حتى 8000
- تُرفض الحقول غير المعروفة بالخطأ 422 invalid_input
الأسعار
التكلفة $0 لكل طلب مع خطة Infinite نشطة: لا تستهلك تنبؤات API أي أرصدة، أيًّا كانت الإعدادات.
أسعار APIمخطط JSON Schema
المخطط نفسه الذي تقدّمه الواجهة عبر GET /v1/models/picassoia/picassoia-reference-to-video.
{
"input_schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"prompt": {
"type": "string",
"minLength": 1,
"maxLength": 8000,
"description": "What happens in the video and what is heard. Name the references: \"Image 1\", \"Video 1\", \"Audio 1\"."
},
"images": {
"description": "Up to 9 reference images (characters, objects, places), in the order of \"Image 1\", \"Image 2\"… At least one image or a video is required.",
"maxItems": 9,
"type": "array",
"items": {
"type": "string",
"description": "A reference image: an https URL or a data URL."
}
},
"video": {
"type": "string",
"description": "Reference video: an https URL (MP4, MOV or WebM, up to 50 MB; its first 15 s are used). The clip follows its movement, camera and timing, keeps its sound unless an audio is sent, and lasts as long as the video, or duration if that is shorter. To put your own character in it, say who replaces whom (\"Image 1 replaces the woman in Video 1\") and what they do."
},
"audio": {
"type": "string",
"description": "Reference audio: an https URL (MP3, WAV, M4A, AAC, OGG or FLAC, up to 20 MB). A voice a character says with lip sync (\"Image 1 says Audio 1\"), or music. It is heard as it is. Lip sync is most exact in clips of up to 5 s."
},
"resolution": {
"default": "480p",
"description": "480p or 720p, both up to 15 s.",
"type": "string",
"enum": [
"480p",
"720p"
]
},
"duration": {
"default": 5,
"description": "Length in seconds.",
"type": "integer",
"minimum": 1,
"maximum": 15
},
"aspect_ratio": {
"description": "Default: 16:9, or the reference video's when there is one. match_input_image follows the video if there is one, otherwise the first image.",
"type": "string",
"enum": [
"match_input_image",
"16:9",
"9:16",
"4:3",
"3:4",
"3:2",
"2:3",
"1:1"
]
},
"video_strength": {
"description": "Only with a video: how closely the clip follows it. high (the default) follows its camera, composition and timing most closely; medium and low follow it more loosely and render faster.",
"type": "string",
"enum": [
"high",
"medium",
"low"
]
},
"save_audio": {
"default": true,
"description": "Keep the generated audio track.",
"type": "boolean"
},
"seed": {
"description": "Random seed. Set it to reproduce a result.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"enhance_prompt": {
"default": true,
"description": "Let PicassoIA rewrite the prompt for a better video before generating it.",
"type": "boolean"
}
},
"required": [
"prompt"
],
"additionalProperties": false
},
"output_schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "string",
"format": "uri",
"description": "URL of the generated video (MP4)."
}
}