مفتاح Seedream API: الوصول المجاني والمنصة التجريبية ومثال Node.js

كتابة Seedream API Key في شريط البحث تقودك إلى مكانين مختلفين جدًا: منصة ByteDance نفسها، وحشد من المواقع التي تستضيف النموذج لك. أيّهما تحتاج يعتمد على ما تنوي إطلاقه. إذا أردت فقط رؤية ما ينتجه Seedream، فلست بحاجة إلى أي بيانات اعتماد. إذا أردت سكربتًا يرسل الأوامر النصية ويحفظ الملفات، فستحتاج إلى حساب لدى مزوّد API، وتختلف المزوّدات كثيرًا في الأسعار والحدود والوصول إلى النماذج. تعرض هذه المقالة كل مسار بمعلومات جرى التحقق منها من الصفحات الرسمية، وتوضح أين يتوقف الوصول المجاني، وتتضمن سكربت Node.js يمكنك تشغيله اليوم. نتيجة تستحق أن تُذكر منذ البداية: واجهة PicassoIA API تقدّم أربعة نماذج خاصة بها، وليس Seedream واحدًا منها، ولهذا فإن المنصة التجريبية هي المكان الذي يوجد فيه Seedream على PicassoIA.

مسارا الوصول إلى Seedream

Seedream عائلة من نماذج الصور من ByteDance، ويظهر اسم النموذج نفسه خلف أبواب مختلفة جدًا. قبل أن تنسخ أي شيفرة، اختر الباب الذي يناسب هدفك.

قاعدة سريعة: إذا كانت النتيجة مجموعة من الصور لمنشور أو عرض، فاستخدم المنصة التجريبية وتوقف عندها. إذا كنت تبني منتجًا يستدعي مستخدموه Seedream مباشرة، فاتجه إلى المزوّد وخصص ميزانية للفوترة حسب الاستخدام من اليوم الأول. إذا كنت تؤتمت دفعات من الصور المصغرة أو التعديلات باستخدام نماذج PicassoIA، فإن تناسبك PicassoIA API، ما دامت خطتك تسمح بذلك. الجمع بين المسارات أمر طبيعي: اكتب المسودة في المنصة التجريبية، ثم انقل الأمر النصي الناجح إلى سكربت.

مسار المنصة التجريبية

أسرع طريقة للبدء هي المتصفح. Seedream 5 Pro يحوّل أمرًا نصيًا، أو حتى 10 صور مرجعية، إلى صورة بدقة 1K أو 2K. أما Seedream 4.5 فيدفع الدقة إلى أبعد من ذلك، مع إخراج 2K و4K بحد أقصى 4096 بكسل، ووضع دفعات يعيد حتى 15 صورة مترابطة في تشغيل واحد. تصف صفحات النموذجين تجربة المتصفح بأنها مجانية وعبر الإنترنت، ولا تتطلب أي كتابة شيفرة.

يناسب هذا المسار من يكرر التجربة بالنظر: يغيّر عبارة إضاءة، يعيد التوليد، ويقارن النتيجتين جنبًا إلى جنب. لكنه لا يناسب مهمة تحتاج إلى 500 صورة بين عشية وضحاها، لأن كل توليد يتطلب نقرة يدوية.

مسار المزوّد المباشر

تشير صفحة Seedream 5 Pro نفسها إلى إرشادات BytePlus، وتذكر أن الأوامر النصية تعمل بأفضل شكل بأقل من 600 كلمة إنجليزية. تدير BytePlus منصة ModelArk الخاصة بها، وهذه اللوحة هي المكان الذي تأتي منه بيانات اعتماد Seedream المباشرة. وفقًا لوثائق ModelArk، تحصل الحسابات الجديدة على حصة تجريبية مجانية للاستدلال تُقاصّ مع رسوم الاستدلال بالدفع حسب الاستخدام. تُحسب هذه الحصة بشكل منفصل لكل نموذج وتُشارك ضمن الحساب الرئيسي. يمر توليد الصور عبر واجهة API لتوليد الصور، التي تعرض نقطة النهاية /images/generations. تُدرج وثائق التكامل الخارجية https://ark.ap-southeast.bytepluses.com/api/v3 بوصفه عنوان URL الأساسي الإقليمي الافتراضي.

💡 انسخ معرّف النموذج أو نقطة النهاية بالضبط من لوحة ModelArk الخاصة بك، لا من مدونة، ولا حتى من هذه المدونة. تتغير المعرّفات مع كل إصدار، ومعرّف قديم يُفشِل الطلب قبل أن يصل إلى النموذج.

لن أطبع عينة شيفرة للمزوّد المباشر هنا عن قصد. شكل الطلب ومعرّفات النماذج تخص BytePlus، وهي تتغير، وتخمين خاطئ يضيّع عليك ظهيرتك. يستخدم مثال Node.js المذكور لاحقًا في هذه المقالة واجهة PicassoIA API، حيث تأتي كل نقطة نهاية وكل حقل وارد أدناه مباشرة من وثائقها.

وصول مجاني دون أي بيانات اعتماد

الوصول المجاني حقيقي، لكن له حدود. إليك ما تدّعيه كل صفحة، وأين تتوقف هذه الادعاءات.

ما تقدمه صفحات النماذج

ماذا لا تعني كلمة مجاني

الوصول المجاني في المتصفح لا يقول شيئًا عن API. تعلن صفحة PicassoIA Image عن توليد غير محدود لتحويل النص إلى صورة دون حد لكل صورة. تذكر وثائق API أن التنبؤات مجانية حاليًا ولا تستهلك أي نقاط، ومع ذلك تسمّي الوثائقُ نفسها خطة Infinite شرطًا، وأي طلب بدونها يعيد 403 plan_required.

تعرض صفحة الأسعار الوصول إلى API على أكثر من مستوى، لذلك تصف الصفحتان هذا الأمر بصيغتين مختلفتين. تحقق من خطتك الخاصة قبل أن تبني منتجًا فوقها. ينطبق التحذير نفسه على الحصص التجريبية للمزوّدين: الحصة التجريبية رصيد بداية، وليست مخصصات دائمة.

يمكن أن ترتبط الحدود أيضًا بالدقة أو بحجم الدفعة أو بعدد الطلبات المتزامنة، لا بعدد ثابت من الصور. اقرأ جدول الحدود في قسم API قبل أن تصمم مهمة دفعية حول رقم رأيته فقط في صفحة هبوط.

كيفية استخدام Seedream 5 Pro

Seedream 5 Pro على PicassoIA سريع الإعداد. اتبع هذه الخطوات بالترتيب:

1. افتح صفحة النموذج. انتقل إلى Seedream 5 Pro وسجّل الدخول.
2. اكتب الأمر النصي. الحد 4000 حرف، لكن توصي BytePlus بالبقاء دون 600 كلمة إنجليزية.
3. اختر الحجم. 1K يساوي نحو 2 ميغابكسل، و2K يساوي نحو 4 ميغابكسل. الافتراضي هو 2K.
4. اختر نسبة العرض إلى الارتفاع. الخيارات هي 1:1 و4:3 و3:4 و16:9 و9:16 و3:2 و2:3 و21:9. الافتراضي match_input_image ينسخ نسبة صورتك المرجعية الأولى.
5. أرفق المراجع إن توفرت. أضف من 1 إلى 10 صور لدمج الوجوه أو الأشياء أو الأساليب في نتيجة واحدة.
6. اضبط صيغة الإخراج وولّد. اختر PNG أو JPEG، وشغّل التوليد، ثم نزّل الملف.

إعدادات الأوامر التي تهم

ثلاثة إعدادات تغيّر النتائج أكثر من أي صفة في الأمر النصي:

• الحجم. استخدم 1K للمسودات و2K لأي شيء ستنشره. انتقل إلى Seedream 4.5 عندما تحتاج إلى 4K، لأن Seedream 5 Pro يصل إلى 2K كحد أقصى.
• عدد المراجع. المزيد من المراجع يضيف ثباتًا لكنه يضيف قيودًا أيضًا. ابدأ باثنتين أو ثلاث، وأضف المزيد فقط عندما ينحرف الوجه أو المنتج.
• نسبة العرض إلى الارتفاع. حدّدها صراحةً عندما يكون للصورة وجهة محددة. ترك النسبة تطابق مرجعًا أمر مريح، لكنه يرث بصمت قصّ تلك الصورة.

💡 صف الضوء، لا المزاج. «ضوء شمس منخفض من اليسار، وظلال طويلة على الرصيف» يمنح النموذج شيئًا يرسمه. «جو درامي» لا يمنحه شيئًا.

إليك أمرًا نصيًا يستخدم هذه الإعدادات جيدًا، مكتوبًا لـ 2K بحجم 16:9: وعاء خزفي من البرتقال على قماش كتان بجانب نافذة، ضوء صباحي منخفض من اليسار، ظلال ناعمة تمتد عبر الطاولة الخشبية، إحساس عدسة 85 ملم، عمق ميداني ضحل، ونسيج الكتان المرئي. يسمّي موضوعًا واتجاه ضوء وملمس سطح في أقل من 50 كلمة. يقبل Seedream 5 Pro أكثر من ذلك بكثير، لكن الأمر النصي القصير والملموس هو الأساس الأفضل: أضف تفصيلًا واحدًا في كل تشغيل، واحتفظ بالتغيير فقط إذا تحسنت الصورة.

مسار PicassoIA API

من أين تأتي بيانات الاعتماد

تُصادق واجهة PicassoIA API للمطورين باستخدام سرّ Bearer يبدأ بالعبارة pia_sk_. تنشئه من حسابك عبر صفحة PicassoIA API، ويمكن لكل حساب أن يحتفظ بسرّين. عامله كما تعامل كلمة المرور: احفظه في متغير بيئة، لا في مستودع أبدًا، واستبدله إذا تسرّب إلى لقطة شاشة أو سجل.

على Node 20.6 أو أحدث يمكنك حفظ المفتاح السري في ملف .env وتحميله باستخدام node --env-file=.env generate.mjs، فلا يدخل أبدًا سجل الأوامر في الطرفية. أضف .env إلى .gitignore قبل أول إيداع (commit). إذا نشرت السكربت، فاضبط المتغير في مدير الأسرار لدى مزوّد الاستضافة بدلًا من نسخ الملف.

النماذج التي تقدمها API

تسرد وثائق API أربعة نماذج:

• PicassoIA Image، المعرّف (slug) picassoia/picassoia-image، لتحويل النص إلى صورة
• PicassoIA Image Editor Pro، المعرّف (slug) picassoia/picassoia-image-editor-pro، للتعديل باستخدام من 1 إلى 4 صور إدخال
• PicassoIA Video، المعرّف (slug) picassoia/picassoia-video
• Seedance 2.5 Lite، المعرّف (slug) picassoia/seedance-2.5-lite، فيديو مع صوت

Seedream ليس ضمن تلك القائمة. إذا قال لك درس تعليمي إن عليك استدعاء نموذج Seedream بسر pia_sk_، فتحقق أولًا من قائمة النماذج في حسابك.

الخطة والحدود

مثال Node.js يعمل

تحتاج إلى Node 18 أو أحدث، فهو يوفر fetch عامًا. احفظ الشيفرة باسم generate.mjs، وصدّر مفتاحك السري باسم PICASSOIA_SECRET، ثم شغّل node generate.mjs.

دالة المساعدة

يتبع هذا المساعد الوثائق الرسمية، مع تغيير واحد: اسم متغير البيئة هو PICASSOIA_SECRET. ينشئ تنبؤًا، وينتظر الفاصل الزمني الذي تقترحه API، ويستطلع الحالة حتى تصل المهمة إلى حالة نهائية، ثم يعيد المخرجات.

const API = 'https://api.picassoia.com/v1'
const headers = {
  Authorization: `Bearer ${process.env.PICASSOIA_SECRET}`,
  '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
}

نسخ الأمر النصي

ولّد أول صورة لك

أضف هذا إلى الملف نفسه. يطلب من PicassoIA Image صورة JPEG واحدة بنسبة 16:9 ويكتبها على القرص.

import { writeFile } from 'node:fs/promises'

const output = await run('picassoia/picassoia-image', {
  prompt: 'A weathered fisherman mending a net on a grey pier at dawn, 35mm film look, soft side light',
  aspect_ratio: '16:9',
  num_outputs: 1,
  output_format: 'jpg',
  output_quality: 80,
})

const [url] = [].concat(output)
const image = await fetch(url)
await writeFile('result.jpg', Buffer.from(await image.arrayBuffer()))
console.log('Saved result.jpg from', url)

نسخ الأمر النصي

سطر [].concat(output) يقبل عنوان URL واحدًا أو قائمة، فيستمر السكربت في العمل مهما كان شكل المخرجات.

حرّر صورة موجودة

PicassoIA Image Editor Pro يحتاج إلى أمر نصي و1 إلى 4 صور. تسرد الوثائق data URLs بحجم يصل إلى 5 ميغابايت لكل منها، لذا اقرأ الملف وشفّره:

import { readFile } from 'node:fs/promises'

const photo = await readFile('portrait.jpg')
const edited = await run('picassoia/picassoia-image-editor-pro', {
  prompt: 'Replace the grey wall with warm red brick, keep the lighting and the face unchanged',
  images: [`data:image/jpeg;base64,${photo.toString('base64')}`],
  aspect_ratio: 'match_input_image',
})
console.log(edited)

نسخ الأمر النصي

الأخطاء والحدود في الممارسة

اقرأ جسم الخطأ

عند فشل الإنشاء، يرمي المساعد الخطأ الأصلي من API، أي code و detail، ولهذا يظهر غياب الخطة في صورة plan_required بدلًا من خطأ شبكة غامض. بعد الإنشاء، ينتقل التنبؤ عبر خمس حالات:

التنبؤ الفاشل لا يعيد تشغيل نفسه، لذا فإن إعادة المحاولة تعني إنشاء تنبؤ جديد. يتعامل غلاف بسيط مع الإخفاقات العابرة، ويتوقف فورًا عند خطأ في الخطة، وهو خطأ لن يصلحه أي انتظار:

async function runWithRetry(model, input, attempts = 3) {
  for (let i = 1; i <= attempts; i++) {
    try {
      return await run(model, input)
    } catch (error) {
      if (i === attempts || String(error.message).startsWith('plan_required')) throw error
      await sleep(i * 5)
    }
  }
}

نسخ الأمر النصي

ابقَ دون خمسة تنبؤات

الحد هو خمسة تنبؤات متزامنة لكل حساب، والعدد مشترك بين كل بيانات الاعتماد وكل توليدات MCP. سكربت دفعات وجلسة دردشة مفتوحة تسحبان من المجموعة نفسها المكونة من خمس. يُبقيك مجمّع عمال صغير دون الحد الأقصى ويترك فتحة واحدة شاغرة:

async function pool(tasks, limit = 4) {
  const results = []
  let next = 0
  const worker = async () => {
    while (next < tasks.length) {
      const i = next++
      results[i] = await tasks[i]()
    }
  }
  await Promise.all(Array.from({ length: limit }, worker))
  return results
}

const prompts = ['a red bicycle against a pale wall', 'a lighthouse on a grey coast']
const images = await pool(
  prompts.map((prompt) => () => run('picassoia/picassoia-image', { prompt, aspect_ratio: '16:9' })),
)

نسخ الأمر النصي

أضف نموذجًا لغويًا وحركة

نادرًا ما تكون الصورة الخطوة الأخيرة. مجموعتان أخريان من PicassoIA تتناسبان مباشرة مع المسار: نماذج لغوية كبيرة قبل الصورة، والفيديو بعدها.

صِغ الأوامر بمساعدة نموذج لغوي

الفكرة من سطر واحد تعطي النموذج القليل ليعمل به. الصقها في Claude Sonnet 5 أو Gemini 3.5 Flash واطلب بنية:

أعد كتابة هذه الفكرة كأمر نصي واحد للصورة بحوالي 120 كلمة، يتضمن الموضوع والمكان واتجاه الضوء والعدسة وملمس السطح: «صياد يصلح شباك الصيد عند الفجر».

أرسل النتيجة إلى Seedream 5 Pro في المنصة التجريبية، أو إلى PicassoIA Image عبر السكربت أعلاه. النماذج الأربعة في API المذكورة سابقًا لا تشمل نموذج محادثة، لذلك تتم هذه الخطوة على الموقع.

حرّك النتائج

بمجرد أن تبدو الصورة الثابتة صحيحة، يمكن لنموذج Seedance 2.5 Lite أن يستخدمها كإطار افتتاحي. تدرج صفحته مقاطع مدتها 5 أو 10 ثوانٍ بدقة 480p أو 720p، مع صوت متزامن، وتصف توليدًا غير محدود لأعضاء Wonder. يقبل PicassoIA Video الإدخال نفسه، أي تحويل الصورة إلى فيديو، بمدة ثابتة هي 5 ثوانٍ بمعدل 24 إطارًا في الثانية. وللمظاهر المنمقة، يقدم PicassoIA أيضًا فئة مؤثرات بها مئات المؤثرات الفيديوية، ويمكن الوصول إليها من صفحة كل النماذج.

صِف الحركة بالترتيب، كما يطلبها المخرج: يسحب الصياد الشبكة نحوه، تنجرف الكاميرا ببطء إلى اليمين، تعبر النوارس السماء الباهتة، ويبقى الضوء الناعم ثابتًا. فعل واحد للشخص، وحركة كاميرا واحدة، وملاحظة إضاءة واحدة تكفي لمقطع قصير.

شغّل أول أمر نصي لـ Seedream

اختر فكرة واحدة، من جملة واحدة، وحوّلها إلى صورة اليوم. افتح Seedream 5 Pro على Picasso IA، والصق أمرًا نصيًا، واختر 2K و16:9، ثم ولّد. شغّل الأمر نفسه على Seedream 4.5 بدقة 4K، وقارن الملفين بالحجم الكامل.

عندما يصبح النقر غير عملي، أنشئ بيانات اعتماد PicassoIA API، والصق المساعد أعلاه في ملف، وأرسل أوامرك النصية عبر PicassoIA Image. غيّر متغيرًا واحدًا في كل تشغيل، واحتفظ بقيم البذرة التي تعجبك، ودع حد الفتحات الخمس يحدد وتيرتك. كل نموذج مذكور هنا على بعد نقرة واحدة في صفحة جميع النماذج.