برای اضافه‌کردن هوش مصنوعی به یک وب‌سایت یا اپلیکیشن لازم نیست مدل را از ابتدا آموزش دهید یا زیرساخت پردازشی بزرگی تهیه کنید. بیشتر قابلیت‌های هوش مصنوعی از طریق API در دسترس‌اند و برنامه شما می‌تواند ورودی کاربر را برای مدل ارسال و نتیجه را دریافت کند.

با استفاده از API هوش مصنوعی می‌توان قابلیت‌هایی مانند موارد زیر را به نرم‌افزار اضافه کرد:

• چت‌بات و دستیار هوشمند
• تولید و بازنویسی متن
• خلاصه‌سازی و ترجمه
• استخراج اطلاعات از اسناد
• جست‌وجوی معنایی و RAG
• تولید و ویرایش تصویر
• تبدیل گفتار به متن
• تولید صوت
• تولید ویدئو از متن
• تبدیل تصویر به ویدئو
• دسته‌بندی پیام‌های کاربران
• تحلیل داده و گزارش‌سازی
• ساخت Agent و گردش کار هوشمند

در این مقاله، ابتدا ساختار فنی اتصال یک اپلیکیشن به مدل هوش مصنوعی را بررسی می‌کنیم و سپس یک پروژه واقعی می‌سازیم که کاربر در سایت توضیح ویدئوی موردنظر خود را وارد می‌کند و برنامه از طریق API درواره و مدل bytedance/seedance-2.5 ویدئو تولید می‌کند.

API هوش مصنوعی چیست؟

API هوش مصنوعی رابطی است که نرم‌افزار شما را به یک مدل هوش مصنوعی متصل می‌کند.

برنامه یک درخواست شامل ورودی کاربر، شناسه مدل و تنظیمات تولید ارسال می‌کند. سرویس API درخواست را پردازش می‌کند و نتیجه را در قالب JSON، فایل، تصویر، صوت یا ویدئو برمی‌گرداند.

فرایند کلی به این شکل است:

کاربر
  ↓
وب‌سایت یا اپلیکیشن
  ↓
سرور نرم‌افزار شما
  ↓
API هوش مصنوعی
  ↓
مدل انتخاب‌شده
  ↓
پاسخ API
  ↓
اعتبارسنجی و ذخیره نتیجه
  ↓
نمایش خروجی به کاربر

برای مثال، اگر کاربر از یک فروشگاه اینترنتی بخواهد توضیحات محصول تولید کند، برنامه می‌تواند نام و ویژگی‌های محصول را به مدل زبانی ارسال کند و متن تولیدشده را دریافت کند.

اگر کاربر بخواهد ویدئو بسازد، برنامه یک درخواست تولید ویدئو ثبت می‌کند، شناسه کار را دریافت می‌کند و پس از پایان پردازش، فایل ویدئو را نمایش می‌دهد.

API درواره چیست؟

درواره یک زیرساخت یکپارچه برای دسترسی به مدل‌های مختلف هوش مصنوعی است. توسعه‌دهنده می‌تواند با یک حساب، یک کلید API و کیف پول ریالی به مدل‌های متنی، تصویری، صوتی و ویدئویی مختلف متصل شود.

آدرس پایه API درواره:

https://api.darvareh.ir/v1

بخش‌های متنی API درواره با ساختار OpenAI سازگارند. بنابراین در بسیاری از پروژه‌ها می‌توانید از SDK رسمی OpenAI استفاده کنید و فقط base_url و شناسه مدل را تغییر دهید.

مزیت این روش آن است که منطق اصلی برنامه به یک شرکت یا مدل خاص وابسته نمی‌شود. برای تغییر مدل معمولاً کافی است شناسه مدل در تنظیمات برنامه عوض شود.

برای مثال:

DARVAREH_MODEL=openai/gpt-4o

می‌تواند بعداً به یک مدل دیگر تغییر کند:

DARVAREH_MODEL=anthropic/claude-sonnet-4

البته قابلیت‌ها و پارامترهای مدل‌ها کاملاً یکسان نیستند و هر مدل باید پیش از استفاده عملی آزمایش شود.

پیش‌نیازهای استفاده از API درواره

برای شروع به موارد زیر نیاز دارید:

1. ساخت حساب در درواره
2. شارژ کیف پول
3. ساخت کلید API
4. انتخاب مدل از فهرست مدل‌ها
5. قراردادن کلید در متغیر محیطی
6. ارسال اولین درخواست از سمت سرور

کلید API معمولاً با چنین ساختاری نمایش داده می‌شود:

sk-darvareh-...

کلید را فقط در سرور نگه دارید. قراردادن API Key در JavaScript مرورگر، کد اپلیکیشن موبایل یا مخزن عمومی باعث می‌شود دیگران بتوانند از اعتبار حساب شما استفاده کنند.

ساخت اولین درخواست متنی با cURL

ساده‌ترین روش آزمایش API استفاده از cURL است:

curl https://api.darvareh.ir/v1/chat/completions \
  -H "Authorization: Bearer YOUR_DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "شما یک دستیار فارسی دقیق و حرفه‌ای هستید."
      },
      {
        "role": "user",
        "content": "سه عنوان برای معرفی یک نرم‌افزار حسابداری پیشنهاد بده."
      }
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

قسمت‌های اصلی درخواست عبارت‌اند از:

آموزش اتصال API درواره با Python

ابتدا SDK را نصب کنید:

pip install openai python-dotenv

فایل .env:

DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_MODEL=openai/gpt-4o

کد Python:

import os

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

client = OpenAI(
    api_key=os.environ["DARVAREH_API_KEY"],
    base_url="https://api.darvareh.ir/v1",
)

response = client.chat.completions.create(
    model=os.getenv("DARVAREH_MODEL", "openai/gpt-4o"),
    messages=[
        {
            "role": "system",
            "content": "شما یک دستیار فارسی دقیق هستید.",
        },
        {
            "role": "user",
            "content": "API هوش مصنوعی را در دو جمله توضیح بده.",
        },
    ],
    temperature=0.3,
    max_tokens=300,
)

print(response.choices[0].message.content)

در یک پروژه واقعی باید برای خطاهای شبکه، محدودیت نرخ و تمام‌شدن اعتبار نیز برنامه‌ریزی کنید:

from openai import (
    APIConnectionError,
    APIStatusError,
    RateLimitError,
)

try:
    response = client.chat.completions.create(
        model=os.environ["DARVAREH_MODEL"],
        messages=[
            {"role": "user", "content": "این متن را خلاصه کن."}
        ],
    )

    print(response.choices[0].message.content)

except RateLimitError:
    print("تعداد درخواست‌ها بیش از حد مجاز است.")

except APIConnectionError:
    print("ارتباط با سرویس برقرار نشد.")

except APIStatusError as error:
    print("خطای API:", error.status_code)

آموزش اتصال API درواره با Node.js

ابتدا بسته‌های موردنیاز را نصب کنید:

npm install openai dotenv

فایل .env:

DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_MODEL=openai/gpt-4o

کد JavaScript:

import "dotenv/config";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DARVAREH_API_KEY,
  baseURL: "https://api.darvareh.ir/v1",
});

const response = await client.chat.completions.create({
  model: process.env.DARVAREH_MODEL,
  messages: [
    {
      role: "system",
      content: "شما یک دستیار فارسی دقیق هستید.",
    },
    {
      role: "user",
      content: "برای یک فروشگاه آنلاین متن معرفی کوتاه بنویس.",
    },
  ],
  temperature: 0.5,
  max_tokens: 500,
});

console.log(response.choices[0].message.content);

در Node.js جدید می‌توان بدون نصب SDK نیز از fetch استفاده کرد:

const response = await fetch(
  "https://api.darvareh.ir/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.DARVAREH_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "openai/gpt-4o",
      messages: [
        {
          role: "user",
          content: "این پیام مشتری را دسته‌بندی کن.",
        },
      ],
    }),
  }
);

if (!response.ok) {
  throw new Error(`Darvareh API error: ${response.status}`);
}

const data = await response.json();
console.log(data.choices[0].message.content);

آموزش اتصال API درواره با PHP

برای پروژه‌های WordPress، Laravel و سایر برنامه‌های PHP می‌توان از cURL استفاده کرد:

<?php

$apiKey = getenv("DARVAREH_API_KEY");

$payload = [
    "model" => "openai/gpt-4o",
    "messages" => [
        [
            "role" => "system",
            "content" => "شما یک دستیار فارسی دقیق هستید."
        ],
        [
            "role" => "user",
            "content" => "یک توضیح کوتاه برای این محصول بنویس."
        ]
    ],
    "temperature" => 0.5,
    "max_tokens" => 500
];

$curl = curl_init(
    "https://api.darvareh.ir/v1/chat/completions"
);

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . $apiKey,
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode(
        $payload,
        JSON_UNESCAPED_UNICODE
    )
]);

$response = curl_exec($curl);
$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);

if ($response === false) {
    throw new Exception(curl_error($curl));
}

curl_close($curl);

if ($statusCode < 200 || $statusCode >= 300) {
    throw new Exception(
        "Darvareh API error: " . $statusCode
    );
}

$data = json_decode($response, true);

echo $data["choices"][0]["message"]["content"];

در Laravel بهتر است کلید در فایل .env قرار گیرد و درخواست از طریق HTTP Client سمت سرور ارسال شود.

اتصال درست API به وب‌سایت یا اپلیکیشن

یکی از مهم‌ترین اشتباه‌ها، ارسال مستقیم درخواست از مرورگر یا اپلیکیشن موبایل به API مدل است.

معماری نادرست:

مرورگر کاربر → API درواره

در این حالت کلید API در اختیار کاربر قرار می‌گیرد.

معماری مناسب:

مرورگر یا موبایل
        ↓
API اختصاصی نرم‌افزار شما
        ↓
احراز هویت، کنترل سهمیه و اعتبارسنجی
        ↓
API درواره
        ↓
مدل هوش مصنوعی

بک‌اند شما باید این مسئولیت‌ها را بر عهده داشته باشد:

• نگهداری امن API Key
• احراز هویت کاربران
• کنترل تعداد درخواست
• محدودکردن طول ورودی
• بررسی مدل‌های مجاز
• ثبت هزینه هر کاربر
• جلوگیری از ارسال درخواست تکراری
• مدیریت خطا و Retry
• ذخیره وضعیت پردازش
• بررسی خروجی پیش از نمایش
• اعمال قوانین کسب‌وکار

سه الگوی اصلی استفاده از مدل‌های هوش مصنوعی

مدل‌های همگام

در مدل‌های متنی معمولاً درخواست ارسال می‌شود و همان اتصال، پاسخ نهایی را برمی‌گرداند:

ارسال سؤال → انتظار کوتاه → دریافت پاسخ

چت، ترجمه و خلاصه‌سازی معمولاً از این الگو استفاده می‌کنند.

Streaming

در چت‌بات بهتر است پاسخ به‌تدریج نمایش داده شود. با فعال‌کردن stream، کاربر لازم نیست تا پایان تولید کل پاسخ منتظر بماند.

نمونه Python:

stream = client.chat.completions.create(
    model=os.environ["DARVAREH_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "یک داستان کوتاه فارسی بنویس.",
        }
    ],
    stream=True,
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

مدل‌های ناهمگام

تولید تصویر یا ویدئو ممکن است زمان بیشتری نیاز داشته باشد. در تولید ویدئو، معمولاً یک Job ساخته می‌شود:

ثبت درخواست
    ↓
دریافت شناسه کار
    ↓
قرارگرفتن در صف
    ↓
پردازش مدل
    ↓
تکمیل یا شکست
    ↓
دریافت فایل خروجی

این همان الگویی است که در پروژه Seedance 2.5 استفاده خواهیم کرد.

پروژه عملی: ساخت سایت تولید ویدئو با Seedance 2.5

فرض کنید می‌خواهیم سایتی بسازیم که کاربر در آن:

1. توضیح صحنه را وارد کند.
2. مدت ویدئو را انتخاب کند.
3. دکمه تولید را بزند.
4. وضعیت پردازش را ببیند.
5. پس از پایان، ویدئو را پخش یا دانلود کند.

شناسه مدل در درواره:

bytedance/seedance-2.5

صفحه مدل و قیمت فعلی:

مشخصات Seedance 2.5 در درواره

Seedance 2.5 یک مدل تولید ویدئو از ByteDance است که طبق معرفی رسمی سازنده برای داستان‌گویی طولانی‌تر، استفاده از منابع چندوجهی، کنترل فریم، ویرایش و توسعه ویدئو طراحی شده است. قابلیت‌ها و پارامترهای قابل‌استفاده ممکن است بر اساس مسیر ارائه تغییر کنند؛ بنابراین پیش از انتشار محصول، صفحه مدل و مستندات درواره را بررسی کنید.

معماری پروژه تولید ویدئو

کاربر
  ↓
فرم تولید ویدئو
  ↓
POST /api/videos
  ↓
سرور اپلیکیشن
  ↓
POST https://api.darvareh.ir/v1/videos
  ↓
دریافت job_id
  ↓
ذخیره Job در پایگاه داده
  ↓
بررسی دوره‌ای وضعیت
  ↓
GET /v1/videos/{id}
  ↓
دانلود از /v1/videos/{id}/content
  ↓
ذخیره در فضای ابری و نمایش به کاربر

مرحله اول: ساخت پروژه Node.js

mkdir seedance-video-app
cd seedance-video-app
npm init -y
npm install express dotenv helmet express-rate-limit

در package.json نوع ماژول را مشخص کنید:

{
  "type": "module"
}

فایل .env:

DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_BASE_URL=https://api.darvareh.ir/v1
DARVAREH_VIDEO_MODEL=bytedance/seedance-2.5
PORT=3000

فایل .env را به Git اضافه نکنید:

.env
node_modules

مرحله دوم: ساخت بک‌اند تولید ویدئو

فایل server.js:

import "dotenv/config";
import express from "express";
import helmet from "helmet";
import rateLimit from "express-rate-limit";

const app = express();

app.use(helmet());
app.use(express.json({ limit: "20kb" }));
app.use(express.static("public"));

const BASE_URL =
  process.env.DARVAREH_BASE_URL ||
  "https://api.darvareh.ir/v1";

const VIDEO_MODEL =
  process.env.DARVAREH_VIDEO_MODEL ||
  "bytedance/seedance-2.5";

const HEADERS = {
  Authorization: `Bearer ${process.env.DARVAREH_API_KEY}`,
  "Content-Type": "application/json",
};

const generationLimiter = rateLimit({
  windowMs: 60 * 1000,
  limit: 3,
  standardHeaders: true,
  legacyHeaders: false,
});

function validatePrompt(value) {
  return (
    typeof value === "string" &&
    value.trim().length >= 10 &&
    value.trim().length <= 1500
  );
}

function validateDuration(value) {
  return Number.isInteger(value) && value >= 4 && value <= 30;
}

async function readApiResponse(response) {
  const contentType = response.headers.get("content-type") || "";

  if (contentType.includes("application/json")) {
    return response.json();
  }

  return {
    message: await response.text(),
  };
}

app.post(
  "/api/videos",
  generationLimiter,
  async (request, response) => {
    try {
      const prompt = request.body.prompt?.trim();
      const duration = Number(request.body.duration);

      if (!validatePrompt(prompt)) {
        return response.status(400).json({
          error:
            "توضیح ویدئو باید بین ۱۰ تا ۱۵۰۰ نویسه باشد.",
        });
      }

      if (!validateDuration(duration)) {
        return response.status(400).json({
          error:
            "مدت انتخاب‌شده برای این برنامه معتبر نیست.",
        });
      }

      /*
       * در محصول واقعی:
       * 1. هویت کاربر را بررسی کنید.
       * 2. موجودی یا سهمیه او را کنترل کنید.
       * 3. درخواست را در پایگاه داده ثبت کنید.
       */

      const upstream = await fetch(`${BASE_URL}/videos`, {
        method: "POST",
        headers: HEADERS,
        body: JSON.stringify({
          model: VIDEO_MODEL,
          prompt,
          duration,
        }),
        signal: AbortSignal.timeout(30_000),
      });

      const data = await readApiResponse(upstream);

      if (!upstream.ok) {
        console.error("Darvareh create error:", data);

        return response.status(502).json({
          error: "ثبت درخواست تولید ویدئو انجام نشد.",
        });
      }

      return response.status(202).json({
        id: data.id,
        status: data.status || "queued",
      });
    } catch (error) {
      console.error(error);

      return response.status(500).json({
        error: "خطای داخلی سرور رخ داد.",
      });
    }
  }
);

app.get("/api/videos/:id", async (request, response) => {
  try {
    const jobId = request.params.id;

    if (!/^[a-zA-Z0-9_-]+$/.test(jobId)) {
      return response.status(400).json({
        error: "شناسه درخواست معتبر نیست.",
      });
    }

    /*
     * در محصول واقعی بررسی کنید این Job متعلق به
     * همان کاربر واردشده باشد.
     */

    const upstream = await fetch(
      `${BASE_URL}/videos/${jobId}`,
      {
        headers: {
          Authorization:
            `Bearer ${process.env.DARVAREH_API_KEY}`,
        },
        signal: AbortSignal.timeout(15_000),
      }
    );

    const data = await readApiResponse(upstream);

    if (!upstream.ok) {
      return response.status(502).json({
        error: "دریافت وضعیت پردازش ممکن نشد.",
      });
    }

    return response.json({
      id: data.id,
      status: data.status,
      progress: data.progress ?? null,
      error:
        data.status === "failed"
          ? data.error || "تولید ویدئو ناموفق بود."
          : null,
    });
  } catch (error) {
    console.error(error);

    return response.status(500).json({
      error: "خطای داخلی سرور رخ داد.",
    });
  }
});

app.get(
  "/api/videos/:id/content",
  async (request, response) => {
    try {
      const jobId = request.params.id;

      if (!/^[a-zA-Z0-9_-]+$/.test(jobId)) {
        return response.status(400).end();
      }

      const upstream = await fetch(
        `${BASE_URL}/videos/${jobId}/content`,
        {
          headers: {
            Authorization:
              `Bearer ${process.env.DARVAREH_API_KEY}`,
          },
          signal: AbortSignal.timeout(120_000),
        }
      );

      if (!upstream.ok || !upstream.body) {
        return response.status(502).json({
          error: "فایل ویدئو آماده دریافت نیست.",
        });
      }

      response.setHeader(
        "Content-Type",
        upstream.headers.get("content-type") || "video/mp4"
      );

      response.setHeader(
        "Content-Disposition",
        `inline; filename="${jobId}.mp4"`
      );

      const arrayBuffer = await upstream.arrayBuffer();
      return response.send(Buffer.from(arrayBuffer));
    } catch (error) {
      console.error(error);

      return response.status(500).json({
        error: "دریافت ویدئو انجام نشد.",
      });
    }
  }
);

app.listen(process.env.PORT || 3000, () => {
  console.log("Server: http://localhost:3000");
});

این نمونه قابل اجراست، اما برای سادگی Jobها را در پایگاه داده ذخیره نمی‌کند. در نسخه واقعی باید شناسه Job، شناسه کاربر، وضعیت، هزینه و زمان ایجاد در پایگاه داده ثبت شوند.

مرحله سوم: ساخت رابط کاربری

پوشه public و فایل public/index.html را ایجاد کنید:

<!doctype html>
<html lang="fa" dir="rtl">
<head>
  <meta charset="UTF-8" />
  <meta
    name="viewport"
    content="width=device-width, initial-scale=1"
  />
  <title>تولید ویدئو با هوش مصنوعی</title>
  <style>
    body {
      max-width: 720px;
      margin: 40px auto;
      padding: 20px;
      font-family: sans-serif;
      background: #0b1020;
      color: #fff;
    }

    textarea,
    select,
    button {
      width: 100%;
      box-sizing: border-box;
      margin-top: 12px;
      padding: 12px;
      border-radius: 8px;
    }

    textarea {
      min-height: 140px;
    }

    button {
      background: #7c3aed;
      color: white;
      border: 0;
      cursor: pointer;
    }

    button:disabled {
      opacity: 0.5;
      cursor: wait;
    }

    video {
      width: 100%;
      margin-top: 24px;
      border-radius: 12px;
    }

    #status {
      margin-top: 16px;
    }
  </style>
</head>
<body>
  <h1>تولید ویدئو با هوش مصنوعی</h1>

  <form id="video-form">
    <label for="prompt">توضیح ویدئو</label>

    <textarea
      id="prompt"
      maxlength="1500"
      required
      placeholder="برای مثال: نمای سینمایی یک فنجان قهوه روی میز چوبی، نور صبح از پنجره وارد می‌شود و بخار آرام بالا می‌رود."
    ></textarea>

    <label for="duration">مدت ویدئو</label>

    <select id="duration">
      <option value="5">۵ ثانیه</option>
      <option value="10">۱۰ ثانیه</option>
    </select>

    <button id="submit-button" type="submit">
      تولید ویدئو
    </button>
  </form>

  <p id="status"></p>
  <video id="result" controls hidden></video>

  <script>
    const form = document.querySelector("#video-form");
    const button = document.querySelector("#submit-button");
    const statusBox = document.querySelector("#status");
    const video = document.querySelector("#result");

    const wait = (milliseconds) =>
      new Promise((resolve) =>
        setTimeout(resolve, milliseconds)
      );

    async function getJson(response) {
      const data = await response.json();

      if (!response.ok) {
        throw new Error(
          data.error || "درخواست با خطا مواجه شد."
        );
      }

      return data;
    }

    async function pollVideo(jobId) {
      const maximumAttempts = 120;

      for (
        let attempt = 0;
        attempt < maximumAttempts;
        attempt += 1
      ) {
        const response = await fetch(
          `/api/videos/${jobId}`
        );

        const data = await getJson(response);

        if (data.status === "completed") {
          return;
        }

        if (data.status === "failed") {
          throw new Error(
            data.error || "تولید ویدئو ناموفق بود."
          );
        }

        statusBox.textContent =
          data.progress !== null
            ? `در حال تولید ویدئو؛ پیشرفت: ${data.progress}٪`
            : "ویدئو در صف پردازش است...";

        await wait(5000);
      }

      throw new Error(
        "پردازش بیش از زمان مورد انتظار طول کشید."
      );
    }

    form.addEventListener("submit", async (event) => {
      event.preventDefault();

      button.disabled = true;
      video.hidden = true;
      video.removeAttribute("src");
      statusBox.textContent = "در حال ثبت درخواست...";

      try {
        const response = await fetch("/api/videos", {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            prompt:
              document.querySelector("#prompt").value,
            duration: Number(
              document.querySelector("#duration").value
            ),
          }),
        });

        const job = await getJson(response);

        statusBox.textContent =
          "درخواست ثبت شد و در صف پردازش قرار گرفت.";

        await pollVideo(job.id);

        video.src = `/api/videos/${job.id}/content`;
        video.hidden = false;
        video.load();

        statusBox.textContent = "ویدئو آماده است.";
      } catch (error) {
        statusBox.textContent = error.message;
      } finally {
        button.disabled = false;
      }
    });
  </script>
</body>
</html>

پروژه را اجرا کنید:

node server.js

سپس آدرس زیر را باز کنید:

http://localhost:3000

نمونه پرامپت واقعی برای Seedance 2.5

برای تولید ویدئوی تبلیغاتی محصول، فقط نام محصول کافی نیست. پرامپت بهتر است سوژه، حرکت، محیط، نور، دوربین و سبک را مشخص کند.

نمونه:

A cinematic product video of a matte black coffee mug on a walnut table.
Warm morning sunlight enters from the left window.
Steam rises slowly from the coffee.
The camera performs a smooth five-second dolly-in.
Shallow depth of field, realistic materials, natural shadows,
premium commercial photography, no text, no logo, 16:9.

ساختار پیشنهادی پرامپت ویدئو:

سوژه اصلی
+ محیط
+ اتفاق و حرکت
+ حرکت دوربین
+ نور
+ سبک بصری
+ نسبت تصویر
+ محدودیت‌های خروجی

برای مدل‌های ویدئویی، پرامپت انگلیسی در بسیاری از سناریوها کنترل دقیق‌تری ایجاد می‌کند؛ اما کیفیت فارسی باید با چند نمونه واقعی آزمایش شود.

تبدیل تصویر به ویدئو

اگر کاربر ابتدا تصویر محصول را بارگذاری کند، می‌توان از آن به‌عنوان فریم اول استفاده کرد.

بدنه درخواست:

const upstream = await fetch(
  "https://api.darvareh.ir/v1/videos",
  {
    method: "POST",
    headers: {
      Authorization:
        `Bearer ${process.env.DARVAREH_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "bytedance/seedance-2.5",
      prompt:
        "The product remains consistent while the camera slowly circles around it, cinematic studio lighting.",
      duration: 5,
      generate_audio: false,
      frame_images: [
        {
          type: "image_url",
          image_url: {
            url: "https://cdn.example.com/product.jpg",
          },
          frame_type: "first_frame",
        },
      ],
    }),
  }
);

بر اساس مستندات فعلی درواره، تصویر ورودی باید یک URL عمومی و مستقیم باشد. فایل بارگذاری‌شده کاربر را ابتدا در فضای ذخیره‌سازی قرار دهید و سپس یک URL موقت در اختیار سرویس تولید ویدئو بگذارید.

برای جلوگیری از دسترسی دائمی به فایل خصوصی می‌توان از Signed URL با زمان انقضای محدود استفاده کرد.

مدیریت تولید ویدئو در محیط واقعی

نمونه قبلی برای آموزش مناسب است، اما یک سرویس تجاری به اجزای بیشتری نیاز دارد.

جدول Jobها

برای هر درخواست چنین اطلاعاتی ذخیره کنید:

وضعیت‌های پیشنهادی

pending
reserved
submitted
queued
processing
completed
failed
expired

استفاده از Worker

در مقیاس واقعی بهتر است Polling توسط مرورگر انجام نشود. یک Worker یا Queue وضعیت درخواست‌ها را بررسی کند.

ابزارهای مناسب عبارت‌اند از:

• BullMQ برای Node.js
• Celery برای Python
• Sidekiq برای Ruby
• Laravel Queue برای PHP
• RabbitMQ
• Redis
• Apache Kafka برای معماری‌های بزرگ‌تر

مرورگر فقط وضعیت ثبت‌شده در سرور شما را دریافت می‌کند.

ذخیره خروجی

وابستگی دائمی به URL خروجی ارائه‌دهنده مناسب نیست. پس از تکمیل Job:

1. فایل را از API دریافت کنید.
2. آن را در فضای ذخیره‌سازی خود قرار دهید.
3. اندازه و نوع فایل را بررسی کنید.
4. URL داخلی یا امضاشده تولید کنید.
5. سیاست حذف فایل را اجرا کنید.

گزینه‌های رایج شامل ذخیره‌سازی‌های سازگار با S3، MinIO، Cloudflare R2 و سرویس‌های ابری مشابه هستند.

مدل مالی برای سایت تولید ویدئو

پیش از ثبت Job باید مشخص شود کاربر چگونه هزینه را پرداخت می‌کند.

روش متداول:

محاسبه قیمت تخمینی
       ↓
رزرو اعتبار کاربر
       ↓
ثبت درخواست در API
       ↓
تکمیل یا شکست پردازش
       ↓
محاسبه هزینه واقعی
       ↓
تسویه یا آزادسازی اعتبار

ارسال درخواست گران‌قیمت پیش از کنترل موجودی می‌تواند هزینه‌ای ایجاد کند که از کاربر دریافت نشده است.

همچنین باید برای موارد زیر سیاست مشخص داشته باشید:

• شکست درخواست پیش از شروع پردازش
• شکست مدل در میانه پردازش
• دریافت پاسخ تکراری
• قطع ارتباط Worker
• نامشخص‌ماندن وضعیت Job
• تفاوت هزینه تخمینی و واقعی
• درخواست بازپرداخت
• حذف فایل توسط کاربر

Idempotency و جلوگیری از سفارش تکراری

اگر کاربر چند بار روی دکمه تولید کلیک کند یا مرورگر درخواست را دوباره بفرستد، نباید چند ویدئوی جداگانه ساخته شود.

فرانت‌اند می‌تواند برای هر درخواست یک شناسه تولید کند:

const requestId = crypto.randomUUID();

این شناسه را همراه درخواست بفرستید و در سرور ذخیره کنید. اگر همان کاربر دوباره همان شناسه را ارسال کرد، Job قبلی را برگردانید.

اتصال اپلیکیشن موبایل به مدل هوش مصنوعی

در Android، iOS، Flutter و React Native نیز API Key در برنامه قرار نمی‌گیرد. حتی اگر کلید در کد مخفی یا Obfuscate شود، امکان استخراج آن وجود دارد.

معماری مناسب:

اپلیکیشن موبایل
      ↓
توکن ورود کاربر
      ↓
بک‌اند اختصاصی شما
      ↓
API درواره

اپلیکیشن موبایل فقط Endpointهای داخلی شما را صدا می‌زند:

POST /api/videos
GET  /api/videos/{id}
GET  /api/videos/{id}/content

ابزارهای پرطرفدار برای ساخت اپلیکیشن هوش مصنوعی

لازم نیست برای هر پروژه از Framework پیچیده استفاده کنید. برای یک قابلیت ساده، SDK و چند درخواست HTTP کافی است.

SDK و ارتباط مستقیم

API درواره در بخش‌های سازگار را می‌توان با SDK رسمی OpenAI فراخوانی کرد.

Frameworkهای ساخت برنامه هوش مصنوعی

برای یک چت‌بات ساده، استفاده مستقیم از SDK سبک‌تر است. Framework زمانی ارزش ایجاد می‌کند که برنامه به ابزار، حافظه، RAG، چند مرحله پردازش یا چند Agent نیاز داشته باشد.

ابزارهای بصری و کم‌کد

همه پروژه‌های قابل مشاهده در GitHub الزاماً مجوز متن‌باز یکسانی ندارند. پیش از استفاده تجاری، مجوز نسخه مورد استفاده را بررسی کنید؛ برای مثال n8n با مجوز Fair-code عرضه می‌شود.

AI Gateway و مدیریت چند مدل

اگر از API درواره استفاده می‌کنید، بسیاری از پیچیدگی‌های اتصال به چند ارائه‌دهنده در لایه درواره مدیریت می‌شود. در معماری‌های بزرگ‌تر همچنان می‌توان یک Gateway داخلی برای سهمیه کاربران، ثبت هزینه و سیاست‌های سازمان ساخت.

ابزارهای اجرای مدل متن‌باز روی سرور شخصی

اجرای محلی برای کنترل بیشتر یا کاربردهای خاص مناسب است، اما مدیریت GPU، ظرفیت، مقیاس، به‌روزرسانی مدل و مانیتورینگ را بر عهده تیم شما می‌گذارد.

یک معماری ترکیبی نیز ممکن است: مدل‌های عمومی از طریق درواره استفاده شوند و مدل‌های اختصاصی سازمان روی زیرساخت داخلی اجرا شوند.

پایگاه داده برداری برای RAG

اگر برنامه باید از روی اسناد شرکت پاسخ دهد، متن‌ها ابتدا به Embedding تبدیل و در یکی از این ابزارها ذخیره می‌شوند.

مانیتورینگ و ارزیابی

ثبت لاگ به معنی ذخیره بدون محدودیت تمام پیام‌های کاربران نیست. اطلاعات حساس را حذف یا ماسک و مدت نگهداری داده را مشخص کنید.

انتخاب ابزار مناسب برای هر پروژه

نکات مهم برای استفاده عملی از API هوش مصنوعی

مدل را در تنظیمات نگه دارید

شناسه مدل را در بخش‌های مختلف کد تکرار نکنید:

DARVAREH_TEXT_MODEL=openai/gpt-4o
DARVAREH_VIDEO_MODEL=bytedance/seedance-2.5

برای هر وظیفه مدل مناسب انتخاب کنید

قوی‌ترین یا گران‌ترین مدل الزاماً بهترین گزینه برای همه کارها نیست. یک مدل اقتصادی ممکن است برای دسته‌بندی مناسب باشد و مدل دیگری برای تولید محتوای پیچیده استفاده شود.

Timeout مشخص کنید

تمام درخواست‌های شبکه باید Timeout داشته باشند. نبود Timeout می‌تواند منابع سرور را برای مدت نامحدود اشغال کند.

Retry را محدود کنید

فقط خطاهای موقت را با فاصله افزایشی Retry کنید. درخواست تولید ویدئو نباید بدون Idempotency دوباره ارسال شود؛ زیرا ممکن است دو بار هزینه ایجاد کند.

ورودی و خروجی را اعتبارسنجی کنید

مدل زبانی ممکن است خروجی ناقص یا غیرمنتظره تولید کند. برای خروجی JSON از Schema و ابزارهایی مانند Pydantic یا Zod استفاده کنید.

مصرف هر کاربر را ثبت کنید

برای هر قابلیت این اطلاعات مفید است:

• تعداد درخواست
• مدل استفاده‌شده
• زمان پاسخ
• مقدار مصرف
• هزینه
• نرخ خطا
• نتیجه نهایی
• شناسه کاربر
• شناسه قابلیت

Promptها را نسخه‌بندی کنید

تغییر Prompt ممکن است کیفیت بخشی از ورودی‌ها را کاهش دهد. Prompt را مانند کد نسخه‌بندی و پیش از انتشار ارزیابی کنید.

از صف پردازش استفاده کنید

برای تولید تصویر، صوت و ویدئو بهتر است پردازش از درخواست اصلی وب جدا شود. Queue از Timeout شدن درخواست و فشار ناگهانی روی سرور جلوگیری می‌کند.

قوانین قطعی را به مدل نسپارید

قیمت، موجودی، مجوز کاربر و اقدامات مجاز باید توسط کد و پایگاه داده کنترل شوند، نه فقط توسط Prompt.

خطاهای رایج در اتصال مدل به اپلیکیشن

قراردادن API Key در Frontend

کلید داخل React، Vue، Flutter یا فایل APK امن نیست. تمام فراخوانی‌ها باید از بک‌اند عبور کنند.

نمایش مستقیم خطای ارائه‌دهنده

خطای کامل upstream ممکن است اطلاعات فنی یا داخلی را افشا کند. خطای مناسب به کاربر نشان دهید و جزئیات را در لاگ امن ثبت کنید.

فرض یکسان‌بودن تمام مدل‌ها

پارامترهای مدل‌های متن، تصویر، صوت و ویدئو متفاوت‌اند. حتی دو مدل ویدئویی ممکن است مدت، نسبت تصویر و ورودی‌های متفاوتی داشته باشند.

Polling بدون محدودیت

بررسی وضعیت در هر ثانیه و بدون سقف زمانی باعث افزایش بار می‌شود. فاصله مناسب، سقف تلاش و Backoff تعیین کنید.

ذخیره‌نکردن شناسه Job

اگر سرور ری‌استارت شود و Job فقط در حافظه باشد، ارتباط میان سفارش کاربر و خروجی مدل از بین می‌رود.

نداشتن ارزیابی هزینه

تولید رسانه معمولاً از درخواست متنی گران‌تر است. پیش از ارائه سرویس عمومی باید سقف مصرف و مدل قیمت‌گذاری مشخص شود.

اعتماد کامل به خروجی مدل

مدل ممکن است پاسخ نادرست، نامرتبط یا نامناسب ایجاد کند. خروجی‌های اثرگذار باید کنترل و در موارد لازم بازبینی شوند.

چک‌لیست انتشار اپلیکیشن هوش مصنوعی

پیش از انتشار بررسی کنید:

• API Key فقط در سرور نگهداری می‌شود.
• کاربران احراز هویت می‌شوند.
• سهمیه و محدودیت نرخ فعال است.
• مدل‌های مجاز در Allowlist قرار دارند.
• طول و نوع ورودی کنترل می‌شود.
• Timeout و مدیریت خطا وجود دارد.
• Retry باعث درخواست تکراری نمی‌شود.
• Jobهای ناهمگام در پایگاه داده ذخیره می‌شوند.
• هزینه هر کاربر ثبت می‌شود.
• خروجی رسانه در فضای ذخیره‌سازی خودتان نگهداری می‌شود.
• Promptها نسخه‌بندی شده‌اند.
• نمونه‌های واقعی برای ارزیابی وجود دارند.
• شرایط استفاده برای کاربر نمایش داده می‌شود.
• امکان گزارش خروجی نامناسب وجود دارد.
• حقوق تصاویر، صداها و محتوای ورودی بررسی می‌شود.
• مستندات و قیمت مدل پیش از انتشار کنترل شده‌اند.

پرسش‌های متداول

چگونه API هوش مصنوعی را به سایت وصل کنیم؟

یک Endpoint در بک‌اند سایت ایجاد کنید. ورودی کاربر را اعتبارسنجی و از سمت سرور به API مدل ارسال کنید. نتیجه پس از بررسی به Frontend برگردانده می‌شود.

آیا می‌توان API درواره را در Python استفاده کرد؟

بله. با تعیین base_url برابر https://api.darvareh.ir/v1 می‌توانید از SDK رسمی OpenAI برای Endpointهای سازگار استفاده کنید.

آیا API درواره با Node.js کار می‌کند؟

بله. می‌توان از OpenAI Node SDK، Fetch یا Axios در بک‌اند Node.js استفاده کرد.

آیا می‌توان در WordPress یا PHP از درواره استفاده کرد؟

بله. درخواست‌ها را می‌توان با cURL، Guzzle یا HTTP Client لاراول از سمت سرور ارسال کرد. کلید نباید در JavaScript قالب WordPress قرار گیرد.

چگونه مدل هوش مصنوعی را در اپلیکیشن موبایل استفاده کنیم؟

اپلیکیشن موبایل باید به بک‌اند شما متصل شود و بک‌اند درخواست را به API درواره بفرستد. قراردادن کلید اصلی در اپلیکیشن موبایل مناسب نیست.

چگونه مدل را تغییر دهیم؟

شناسه مدل را در متغیر محیطی نگه دارید. در API سازگار، معمولاً می‌توان با تغییر model از مدل دیگری استفاده کرد؛ اما پارامترها و کیفیت آن باید آزمایش شوند.

آیا Seedance 2.5 از طریق درواره در دسترس است؟

در فهرست فعلی مدل‌های درواره، Seedance 2.5 با شناسه bytedance/seedance-2.5 ثبت شده است. موجودی، قیمت، مسیر ارائه و پارامترهای مدل ممکن است تغییر کنند و باید پیش از استفاده از صفحه مدل بررسی شوند.

چرا تولید ویدئو بلافاصله پاسخ نمی‌دهد؟

تولید ویدئو پردازشی زمان‌بر و ناهمگام است. ابتدا Job ثبت می‌شود، سپس برنامه وضعیت آن را بررسی می‌کند و بعد از تکمیل، فایل خروجی دریافت می‌شود.

آیا برای ساخت برنامه هوش مصنوعی به LangChain نیاز داریم؟

خیر. برای بسیاری از قابلیت‌های ساده، SDK مستقیم کافی است. LangChain و ابزارهای مشابه برای گردش‌های چندمرحله‌ای، RAG، ابزارها و Agentها مفیدند.

بهترین ابزار متن‌باز برای ساخت اپلیکیشن هوش مصنوعی چیست؟

پاسخ به نوع پروژه بستگی دارد. برای RAG می‌توان LlamaIndex یا Haystack، برای Agent از LangGraph، برای رابط وب از Vercel AI SDK، برای اجرای محلی از Ollama یا vLLM و برای مانیتورینگ از Langfuse استفاده کرد.

جمع‌بندی

اتصال مدل هوش مصنوعی به یک اپلیکیشن فقط ارسال یک درخواست API نیست. نسخه عملی محصول به بک‌اند امن، احراز هویت، کنترل هزینه، مدیریت Job، ذخیره خروجی، ارزیابی کیفیت و رسیدگی به خطاها نیاز دارد.

برای شروع:

1. یک قابلیت مشخص انتخاب کنید.
2. مدل مناسب را از فهرست مدل‌ها پیدا کنید.
3. کلید API درواره بسازید.
4. آدرس پایه را روی https://api.darvareh.ir/v1 قرار دهید.
5. اولین درخواست را از سمت سرور ارسال کنید.
6. ورودی و خروجی را اعتبارسنجی کنید.
7. مصرف هر کاربر را ثبت کنید.
8. قابلیت را ابتدا برای گروه محدودی آزمایش کنید.
9. کیفیت، هزینه و زمان پاسخ را اندازه‌گیری کنید.
10. سپس آن را وارد محصول اصلی کنید.

با این معماری می‌توانید قابلیت‌های متنی، تصویری، صوتی و ویدئویی را بدون ساخت مدل از ابتدا به سایت، اپلیکیشن موبایل، فروشگاه اینترنتی، CRM یا نرم‌افزار سازمانی اضافه کنید.

برای مشاهده Endpointهای فعلی، پارامترهای مدل‌های رسانه‌ای و نمونه کدها به مستندات API درواره مراجعه کنید.

مقالات مرتبط

• API هوش مصنوعی چیست؟
• API سازگار با OpenAI چیست؟
• آموزش اتصال API هوش مصنوعی به نرم‌افزار
• Structured Outputs چیست؟
• آموزش LlamaIndex و ساخت RAG
• آموزش Open WebUI و اتصال به درواره
• آموزش اتصال Cursor به درواره
• معرفی و مقایسه مدل‌های هوش مصنوعی

منابع

• مستندات API درواره
• صفحه مدل Seedance 2.5 در درواره
• معرفی رسمی Seedance 2.5 توسط ByteDance
• مستندات رسمی Video Generation در BytePlus
• OpenAI Python Library
• OpenAI Node.js Library
• Vercel AI SDK
• LangChain
• LlamaIndex
• Haystack
• Langfuse
• Promptfoo

این مقاله صرفاً با هدف آموزش و اطلاع‌رسانی تهیه شده است. پیش از استفاده عملی، مستندات رسمی سرویس‌ها و صفحه سلب مسئولیت را مطالعه کنید.