نکته

چنانچه به سرویس‌های متیس از داخل ایران دسترسی دارید از آدرس https://api.metisai.ir استفاده کنید. و چنانچه از سرویس‌هایی که ایران را تحریم کرده‌اند استفاده می‌کنید از https://api.tapsage.com برای استفاده از سرویس‌های متیس استفاده کنید(مانند Colab, یا Kaggle).

جنریشن‌ها

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

با کلیک بر روی هر کدام از مدل‌ها وارد صفحه‌ی مربوط به آن می‌شوید. در این صفحه به راحتی می‌توانید با مدل کار کنید، پارامترهای مختلف آن را تنظیم کنید و خروجی دریافت کنید. همچنین با کمک دکمه‌ی کپی کردن curl که در پایین صفحه قرار دارد می‌توانید نمونه‌ی درخواست برای ارتباط با این مدل از طریق API را دریافت کنید.

سازوکار API

مدل‌های موجود در جنریشن معمولا در دسته‌ی مدل‌هایی قرار می‌گیرند که عملیات زمانبری را انجام می‌دهند، مانند تولید ویدئو. از این روی نحوه‌ی ارتباط با این مدل‌ها به صورت ناهمزمان(Async) می‌باشد. بدین ترتیب کار کردن با این مدل‌ها شامل دو مرحله است:

1. درخواست ساخت یک جنریشن(تولید عکس، ویرایش عکس و ...): در این مرحله شما مدل را با تنظیمات دلخواه فراخوانی می‌کنید.
2. درخواست دریافت نتیجه: در این مرحله شما یا به شکل وبهوک(Webhook) و یا Pulling نتیجه را دریافت می‌کنید.

ساخت جنریشن

مرحله‌ی اول یا همان ساخت جنریشن به زبان ساده، همان درخواستی است که شما به سمت مدل ارسال می‌کنید تا تصویری را ویرایش کنید یا صدایی را تولید کنید. درخواست ساخت حنریشن هر مدل را می‌توانید در صفحه‌ی جنریشن همان مدل در داشبورد متیس کپی کنید. کافی است تا روی دکمه‌ی کپی کردن curl کلیک کنید تا شکل کامل درخواست برای شما نمایش داده شود. در این صفحه همچنین می‌توانید پارامترهای متخلف را تنظیم کنیدو خروجی مد نظر را ارزیابی کنید. در تصویر زیر نمونه‌ی curl برای ساخت تصویر با مدل Nano Banana را مشاهده می‌کنید. شما می‌توانید با هر زبان برنامه‌نویسی‌ای که استفاده می‌کنید درخواست curl مورد نظر خود را پیاده‌سازی کنید.

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

{
  "id": "5de0fa95-8fc9-46c5-9ff2-2237d3acf1e3",
  "createdAt": 1764504657249,
  "finishedAt": null,
  "model": {
    "name": "google",
    "model": "nano-banana-pro"
  },
  "prompt": "A red car",
  "status": "WAITING",
  "error": null,
  "percentage": null,
  "generations": null,
  "usage": null,
  "rawResponse": null
}

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

فیلد	توضیحات
id	شناسه یکتای جنریشن که برای پیگیری وضعیت و دریافت نتیجه استفاده می‌شود
createdAt	زمان ساخت جنریشن به میلی‌ثانیه
finishedAt	زمان اتمام جنریشن (در صورتی که هنوز تمام نشده باشد مقدار null خواهد بود)
model	اطلاعات مدل استفاده شده شامل نام و نوع مدل
prompt	متن درخواستی که برای تولید محتوا ارسال شده است
status	وضعیت فعلی جنریشن که می‌تواند یکی از مقادیر زیر باشد: • QUEUE: جنریشن در صف انتظار قرار دارد • WAITING: در حال انتظار برای شروع پردازش • RUNNING: در حال پردازش و اجرا • COMPLETED: پردازش با موفقیت تکمیل شده است • ERROR: در حین پردازش خطایی رخ داده است • CANCELLED: جنریشن توسط کاربر لغو شده است
error	در صورت بروز خطا، اطلاعات خطا در این فیلد قرار می‌گیرد
percentage	درصد پیشرفت پردازش (در صورت پشتیبانی توسط مدل)
generations	نتیجه نهایی جنریشن که پس از تکمیل شدن، شامل لینک‌های دانلود فایل‌های تولید شده خواهد بود
usage	اطلاعات مصرف منابع و هزینه. در حال حاضر صرفا شامل فیلد cost می‌باشد.
rawResponse	پاسخ خام دریافتی از مدل

دریافت نتیجه

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

Webhook

با کمک این قابلیت به محض این که نتیجه‌ی درخواست شما آماده شود، نتیجه به آدرسی که در زمان ارسال درخواست تنظیم کرده‌اید ارسال می‌شود. شما می‌توانید آدرس وبهوک را در زمان ساخت جنریشن تنظیم کنید. در زمان کپی کردن curl از صفحه‌ی مدل در متیس می‌توانید آدرس webhook خود را تنظیم کنید. زمانی که ساخت جنریشن به پایان برسد(چه موفق باشد چه ناموفق) به آدرسی که تنظیم کرده‌اید اطلاعات زیر ارسال می‌شود:

{
  "id": "5de0fa95-8fc9-46c5-9ff2-2237d3acf1e3",
  "createdAt": 1764504657249,
  "finishedAt": 1764504688985,
  "model": {
    "name": "google",
    "model": "nano-banana-pro"
  },
  "prompt": "A red car",
  "status": "COMPLETED",
  "error": null,
  "percentage": 100,
  "generations": [
    {
      "url": "https://addresstoimage.com",
      "contentType": "IMAGE",
      "content": null
    }
  ],
  "usage": {
    "cost": 0.14
  },
  "rawResponse": null
}

همانطور که می‌بینید پاسخ دریافتی همان پاسخی است که در زمان ساخت جنریشن دریافت کرده بودید ولی با این تفاوت که فیلد generations به آن اضافه شده و مقدار دارد. فیلد url حاوی پاسخ مورد نظر شماست. این پاسخ با موفقیت به سرانجام رسیده و شامل هیچ خطایی نمی‌شود و همچنین ۱۴ سنت هزینه در پی داشته است که از حساب شما در متیس کسر شده. در صورتی که تعداد زیادی درخواست همزمان ارسال می‌کنید، می‌توانید اطلاعات آنها در پایگاه داده ذخیر کنید و در زمان دریافت پاسخ آی‌دی دریافتی را با آی‌دی‌های درخواست‌های خود مطابقت دهید تا متوجه شوید کدام یک از درخواست‌های شما تمام شده است.

Pulling

در این روش به‌جای این که منتظر دریافت پاسخ از سوی متیس باشید به صورت تناوبی درخواست دریافت نتیجه را به متیس ارسال می‌کنید، مثلا هر ۵ ثانیه یکبار. برای دریافت آپدیت از وضعیت جنریشن می‌توانید آی‌دی دریافتی در زمان ساخت جنریشن را به آدرس زیر ارسال کنید:

GET api/v2/generate/

cURL

curl --location --request GET 'https://api.metisai.ir/api/v2/generate/{TASK_ID}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer METIS_API_KEY'

Python

import requests

task_id = 'YOUR_TASK_ID_HERE'
url = f'https://api.metisai.ir/api/v2/generate/{task_id}'

headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer METIS_API_KEY'
}

response = requests.get(url, headers=headers)

print(f"Status Code: {response.status_code}")
print(f"Response: {response.json()}")

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

{
  "id": "5de0fa95-8fc9-46c5-9ff2-2237d3acf1e3",
  "createdAt": 1764504657249,
  "finishedAt": null,
  "model": {
    "name": "google",
    "model": "nano-banana-pro"
  },
  "prompt": "A red car",
  "status": "RUNNING",
  "error": null,
  "percentage": 0,
  "generations": null,
  "usage": null,
  "rawResponse": null
}

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

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

ارسال فایل

اگر نیاز به ارسال فایل(صوتی، تصویری یا ...) برای مدلی بود باید فایل را در یک آدرس عمومی بارگذاری کنید و آدرس دانلود مستقیم آن را برای مدل ارسال کنید. چنانچه بر روی سرورهای خود یا فضاهای ابری این امکان برای شما برقرار نبود می‌توانید از فضای ابری متیس بدین منظور استفاده کنید. از این بخش می‌توانید به مستندات آپلود فایل در متیس دسترسی داشته باشید.

چند نمونه

در این بخش چند نمونه از جنریشن‌ها و مدل‌های متیس را به شما آموزش می‌دهیم. توجه داشته باشید که سازوکار کلی همان مواردی است که توضیح دادیم و این موارد صرفا به عنوان مثال آورده شده‌اند.

ویرایش تصویر با Nano Banana

در کد پایتون زیر ابتدا یک فایل بر روی فضای ابری متیس آپلود می‌شود و سپس با یک پرامپت به ویرایش آن تصویر با کمک مدل Nano Banana پرداخته می‌شود:

import requests
import time

# Configuration
METIS_API_KEY = "METIS_API_KEY"
BASE_URL = "https://api.metisai.ir"
IMAGE_FILE_PATH = "PATH/TO/IMAGE.jpeg"

# Step 1: Upload image
print("Uploading image...")
with open(IMAGE_FILE_PATH, 'rb') as file:
    upload_response = requests.post(
        f"{BASE_URL}/api/v1/storage",
        headers={"Authorization": f"Bearer {METIS_API_KEY}"},
        files={'files': file}
    )

image_url = upload_response.json()['files'][0]['url']
print(f"Image uploaded: {image_url}")

# Step 2: Create generation
print("\nCreating generation...")
generation_response = requests.post(
    f"{BASE_URL}/api/v2/generate",
    headers={
        "Authorization": f"Bearer {METIS_API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "model": {"name": "google", "model": "nano-banana"},
        "operation": "Imagine",
        "args": {"prompt": "remove button from the screenshot", "image_input": image_url}
    }
)

task_id = generation_response.json()['id']
print(f"Task ID: {task_id}")

# Step 3: Poll for results
print("\nWaiting for results...")
while True:
    time.sleep(5)
    
    status_response = requests.get(
        f"{BASE_URL}/api/v2/generate/{task_id}",
        headers={"Authorization": f"Bearer {METIS_API_KEY}"}
    )
    
    data = status_response.json()
    status = data['status']
    
    print(f"Status: {status}")
    
    if status == "COMPLETED":
        print(f"\n✅ Completed! Cost: {data['usage']['cost']} cents")
        print(f"Result: {data['generations'][0]['url']}")
        break
    elif status in ["ERROR", "CANCELLED"]:
        print(f"\n❌ Failed: {data.get('error', 'Cancelled')}")
        break