রিকোয়েস্ট

একটি রিকোয়েস্ট হলো একটি মডেলের একটি কল। এতে একটি আইডি (req_…), একটি স্ট্যাটাস, API ক্রেডিটে এর খরচ (1000 = 1 USD), এবং সফল হলে জেনারেট করা ফাইল থাকে। নিচের প্রতিটি এন্ডপয়েন্টে, প্রতিটি মডেলের জন্য একই অবজেক্ট ফেরত আসে।

একটি মডেল খুঁজুন#

সব ১,৪৯৬টি মডেলের ক্যাটালগ পাবলিক JSON (কোনো কী প্রয়োজন নেই):

curl "https://api.doitong.com/v1/models?category=text-to-video&lab=Google&limit=20"

প্রতিটি সারিতে id, name, lab, category, family, summary, tags, output_kind, docs_url এবং একটি price অবজেক্ট থাকে (Pricing দেখুন)। GET https://api.doitong.com/v1/models/{model_id} সম্পূর্ণ ইনপুট ও আউটপুট JSON Schema, ক্যানোনিক্যাল প্যারামিটারের নাম, মূল্যের নিয়ম এবং একটি উদাহরণ ইনপুট যোগ করে। অজানা category বা mode হলে 400 invalid_parameter ফেরত আসে।

একটি মডেল চালান#

curl -X POST "https://api.doitong.com/v1/run/{model_id}?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-cover" \
  -d '{"prompt": "..."}'

• বডি হলো মডেলের ইনপুট, একটি JSON অবজেক্ট। প্রতিটি মডেল পেজে এর প্যারামিটার তালিকাভুক্ত থাকে।
• কোনো কিছুতে চার্জ করার আগে ইনপুট যাচাই করা হয়। অবৈধ ইনপুট হলে আপত্তিকর param-সহ 422 invalid_input ফেরত আসে এবং কোনো খরচ হয় না।
• ?wait=N (সর্বোচ্চ 20 সেকেন্ড) রিকোয়েস্ট শেষ হওয়া বা সময় শেষ হওয়া পর্যন্ত কলটি ধরে রাখে।
• ?webhook_url=https://… রিকোয়েস্ট শেষ হলে ওই URL-এ একটি স্বাক্ষরিত POST পাঠায় (Webhooks দেখুন)।
• ?storage=permanent বা ?storage=temporary আউটপুট ফাইল কতক্ষণ রাখা হবে তা নির্ধারণ করে; এটি না দিলে অ্যাকাউন্টের সেটিং প্রযোজ্য হয় (ফাইল কোথায় থাকে দেখুন)।

রিকোয়েস্ট কাজ চলাকালীন রেসপন্স হলো 202 Accepted, আর অপেক্ষার মধ্যে শেষ হলে (অথবা এটি রিপ্লে হলে, নিচে দেখুন) 200 OK। Location এবং Doitong-Request-Id হেডারে রিকোয়েস্টের URL ও আইডি থাকে।

স্ট্যাটাস#

সময়সীমার চেয়ে বেশি সময় চলা রিকোয়েস্ট timeout কোডে ব্যর্থ হয় এবং এর অর্থ ফেরত দেওয়া হয়: ছবির জন্য 15 মিনিট, ভিডিওর জন্য 60 মিনিট, অডিও ও অন্যান্য সবকিছুর জন্য 30 মিনিট।

রিকোয়েস্ট অবজেক্ট#

{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:01Z",
  "completed_at": "2026-10-20T12:00:02Z",
  "queue_position": null,
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "input": { "prompt": "..." },
  "output": { "images": [ { "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "width": 1024, "height": 768 } ] },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "content_type": "image/jpeg",
      "width": 1024, "height": 768, "file_size": 183920, "stored": true }
  ],
  "error": null,
  "metrics": { "inference_seconds": 1.2 },
  "storage": { "mode": "permanent", "bytes": 183920, "expires_at": null, "expired": false },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}

• outputs প্রতিটি মডেলের জন্য একই: জেনারেট করা প্রতি ফাইলের জন্য একটি এন্ট্রি, যাতে type (image, video, audio, file বা 3d), আমাদের স্টোরেজের একটি url, content_type এবং জানা থাকলে file_size, width, height, duration থাকে।
• output হলো মডেলের নিজস্ব ফলাফল অবজেক্ট (এর ফিল্ডগুলো প্রতিটি মডেল পেজে তালিকাভুক্ত), যাতে একই URL থাকে।
• storage জানায় ফাইলগুলো কীভাবে রাখা হয়: mode (permanent বা temporary), সংরক্ষিত bytes, expires_at (অস্থায়ী ফাইল মুছে ফেলার সময়, স্থায়ী ফাইলের জন্য null) এবং expired (ফাইল চলে গেলে true)।
• cost.credits হলো API ক্রেডিটে কলের মূল্য (cost.usd USD-তে), cost.charged হলো API ব্যালান্স থেকে ডেবিট করা পরিমাণ, cost.refunded হলো ফেরত আসা পরিমাণ। metered মডেলের ক্ষেত্রে cost.credits হলো শুরুতে ধরে রাখা সর্বোচ্চ পরিমাণ (cost.held); রান সফল হলে cost.settled ব্যবহারের মোট পরিমাণ জানায় এবং সর্বোচ্চ সীমার অবশিষ্ট অংশ cost.refunded-এ থাকে (ব্যবহার অনুযায়ী চার্জ দেখুন)।
• রিকোয়েস্ট ব্যর্থ হলে, error হলো { "type": …, "code": …, "message": … }।

একটি রিকোয়েস্ট পড়ুন#

curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

• ?wait=N (সর্বোচ্চ 20 সেকেন্ড) লং-পোল করে: রিকোয়েস্ট চূড়ান্ত হলেই, অথবা N সেকেন্ড পর বর্তমান স্টেটসহ কলটি ফেরত আসে। ফলাফলের জন্য অপেক্ষা করার সবচেয়ে সহজ উপায় হলো এটিতে লুপ করা।
• ?logs=1 মডেলের অগ্রগতির লগ লাইনগুলো (শেষ 50টি) logs হিসেবে যোগ করে।

শুধু নিজের অ্যাকাউন্টের রিকোয়েস্ট পড়তে পারবেন; অন্য কোনো আইডি হলে 404 request_not_found।

রিকোয়েস্টের তালিকা দিন#

curl "https://api.doitong.com/v1/requests?limit=20&status=succeeded&model=flux/schnell" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

নতুনগুলো আগে। limit হলো 1 থেকে 100 (ডিফল্ট 20), status এবং model ফিল্টার করে। রেসপন্স হলো { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }; পরের পেজের জন্য cursor=<next_cursor> পাঠান।

একটি রিকোয়েস্ট বাতিল করুন#

curl -X POST "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

• মডেল শুরু হওয়ার আগে বাতিল হলে: স্ট্যাটাস canceled হয়, API ক্রেডিট ফেরত দেওয়া হয় এবং আপনি 200 পান।
• ইতিমধ্যে জেনারেট হলে: বাতিলের অনুরোধটি পাঠানো হয় এবং আপনি "cancel_requested": true-সহ 202 পান। মডেল তবুও শেষ হয়ে গেলে রিকোয়েস্ট স্বাভাবিকভাবে সফল হয় এবং চার্জ করা হয়।
• ইতিমধ্যে চূড়ান্ত হলে: 409 not_cancelable (ইতিমধ্যে canceled হওয়া রিকোয়েস্ট শুধু 200 ফেরত দেয়)।

একটি রিকোয়েস্টের ফাইল মুছুন#

curl -X DELETE "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

রিকোয়েস্টের আউটপুট ফাইলের আমাদের কপিগুলো এখনই মুছে দেয় এবং স্টোরেজ চার্জ বন্ধ করে। রেসপন্স হলো storage.expired: true-সহ রিকোয়েস্ট অবজেক্ট; রেকর্ডে URL থাকলেও সেগুলো আর কাজ করে না। আবার কল করলে কোনো পরিবর্তন হয় না (200)। queued বা running অবস্থার রিকোয়েস্টে এখনও কোনো ফাইল নেই: 409 request_active। models:run প্রয়োজন।

Idempotency: দুবার অর্থ না দিয়ে আবার চেষ্টা#

নেটওয়ার্ক ব্যর্থ হতে পারে। নিরাপদে রান আবার চেষ্টা করতে Idempotency-Key হেডার পাঠান (255 অক্ষর পর্যন্ত যেকোনো স্ট্রিং, প্রতি অপারেশনের জন্য ইউনিক; যেমন আপনার নিজস্ব অর্ডার আইডি):

• আগের মতো একই কী ও একই বডি: মূল রিকোয়েস্টটি ফেরত পাবেন (200, হেডার Idempotent-Replayed: true) এবং আবার কোনো চার্জ হবে না।
• মডেলে পৌঁছানোর আগে ব্যর্থ হওয়া রানের পর একই কী ও বডি (upstream_error বা সাবমিটে internal_error, insufficient_credits, budget_exceeded, too_many_inflight): কিছু তৈরি হয়নি এবং কোনো চার্জ হয়নি, তাই ব্যর্থতা ফেরত না দিয়ে আবার মডেল চালানো হবে।
• ভিন্ন বডির সঙ্গে একই কী: 409 idempotency_mismatch।
• কীগুলো যে API কী পাঠিয়েছে, তার আওতায় থাকে।

ফাইল কোথায় থাকে#

রিকোয়েস্টকে succeeded হিসেবে চিহ্নিত করার আগে প্রতিটি আউটপুট ফাইল আমাদের স্টোরেজে কপি করা হয়, তাই outputs-এর URL আমাদের নিজস্ব হোস্টে থাকে এবং আপনি সরাসরি সেগুলোর লিংক দিতে পারেন। কতক্ষণ থাকবে, তা আপনার পছন্দ:

• নতুন রিকোয়েস্টের জন্য অ্যাকাউন্ট সেটিং নির্ধারক: ড্যাশবোর্ড-এর "ফাইল চিরকাল সংরক্ষণ করুন" সুইচ, অথবা PATCH https://api.doitong.com/v1/account/storage-এ {"mode": "temporary"}। GET https://api.doitong.com/v1/account-এর storage-এর অধীনে এটি দেখা যায়, সঙ্গে রাখা বাইট ও মাসিক আনুমানিক খরচ।
• একটি রানে ?storage=permanent|temporary (MCP run টুলের storage আর্গুমেন্ট) সেই রানের জন্য এটিকে ওভাররাইড করে।
• সেটিং পরিবর্তন করলে আগে থেকে থাকা ফাইলগুলোর ওপর কোনো প্রভাব পড়ে না; DELETE /requests/{id}/files দিয়ে সেগুলো মুছুন।
• স্টোরেজের মূল্য দেওয়ার মতো API ব্যালান্স না থাকলে কোনো চার্জ হয় না এবং আপনি একটি ইমেইল পান: ৩০ দিনের মধ্যে টপ-আপ করুন, অথবা রাখা ফাইলগুলো অস্থায়ী হয়ে যাবে এবং ৭ দিন পর মুছে ফেলা হবে।

বিরল ক্ষেত্রে আমাদের কপি ব্যর্থ হলে, এন্ট্রিতে "stored": false থাকে এবং URL-টি মূল, স্বল্পস্থায়ী URL হয়: দ্রুত ডাউনলোড করুন।