Мазмұнға өту
Қазақша
API кілтін алу
API нұсқаулығы

Сұраулар

Markdown ретінде көру Жаңартылды

Сұрау — бір модельді бір рет шақыру. Оның id (req_…), күйі, API кредиттеріндегі құны (1000 = 1 USD) және сәтті орындалған кезде жасалған файлдары болады. Төмендегі әр соңғы нүктеден әр модель үшін бірдей нысан қайтарылады.

Модельді табу

Барлық 1 496 модельдің каталогы жалпыға қолжетімді JSON болып табылады (кілт қажет емес):

терминал
curl "https://api.doitong.com/v1/models?category=text-to-video&lab=Google&limit=20"
Сұрау параметрі Мағынасы
q Атауда, id-де, жасаушыда немесе тегтерде түгел кездесуі тиіс сөздер, мысалы kling 3.
category Бір санат id-і, мысалы text-to-video немесе upscale. GET https://api.doitong.com/v1/categories барлық 21 санатты олардың санымен бірге көрсетеді.
lab Модельді жасаушының атауы немесе id-і, мысалы Google немесе black-forest-labs.
family Алдыңғы жолдағы family id-і: бір модельдің әр нұсқасы (pro, fast, image-to-video, …).
mode exact (баға кіріске қарай есептеледі), measured (кіріс файлдарының ұзындығына немесе өлшеміне қарай), estimate (әр іске қосуға болжалды баға) немесе metered (нақты пайдалануға қарай, бір іске қосудағы максимумға дейін алынады).
limit, cursor Бет өлшемі (1-ден 100-ге дейін, әдепкі 50) және алдыңғы беттің next_cursor мәні.

Әр жолда id, name, lab, category, family, summary, tags, output_kind, docs_url және price нысаны болады (Баға белгілеу бөлімін қараңыз). 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 жібереді (Вебхуктар бөлімін қараңыз).
  • ?storage=permanent немесе ?storage=temporary шығыс файлдарының қанша уақыт сақталатынын таңдайды; көрсетілмесе, аккаунт параметрі қолданылады (Файлдар қайда сақталады бөлімін қараңыз).

Сұрау әлі орындалып жатқанда жауап 202 Accepted, ал күту уақытында аяқталса (немесе қайта ойнату болса, төменде қараңыз) 200 OK болады. Location және Doitong-Request-Id тақырыптары сұрау URL-і мен id-ін қамтиды.

Күйлер

Сұраудың өмірлік циклі
  1. queued Қабылданды және ақысы алынды, воркерді күтуде
  2. running Модель жасап жатыр
  3. Соңғы күйлер:
    • succeededЕсептелген сома алынды; outputs[] ішінде қоймамыздағы URL мекенжайлары бар
    • failedАвтоматты түрде қайтарылды; қате себебін көрсетеді
    • canceledНәтижеге дейін тоқтатылды; қаражат қайтарылды
Күй Мағынасы Соңғы ма?
queued Қабылданды және ақы алынды, орындаушыны күтуде. queue_position кезектегі орнын көрсетуі мүмкін. жоқ
running Модель жасап жатыр. жоқ
succeeded Дайын. outputs файлдарды көрсетеді. иә
failed Модель немесе шектеу оны тоқтатты. error себебін көрсетеді. API кредиттері қайтарылады. иә
canceled Нәтиже жасалмай тұрып тоқтатылды. API кредиттері қайтарылады. иә

Уақыт шегінен ұзақ орындалған сұрау timeout кодымен сәтсіз аяқталады және қайтарылады: кескіндер үшін 15 минут, бейне үшін 60 минут, аудио және қалғанының бәрі үшін 30 минут.

Сұрау нысаны

JSON
{
  "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 (temporary файл жойылатын уақыт, тұрақты файлдар үшін 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 ретінде қосады.

Тек өз аккаунтыңыздың сұрауларын оқи аласыз; кез келген басқа id 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-Key тақырыбын жіберіңіз (255 таңбаға дейінгі кез келген жол, әр операция үшін бірегей, мысалы өз тапсырысыңыздың id-і):

  • Бұрынғыдай кілт және сол дене: бастапқы сұрау қайтарылады (200, Idempotent-Replayed: true тақырыбымен), ақы қайта алынбайды.
  • Модельге жетпей сәтсіз аяқталған іске қосудан кейінгі сол кілт пен сол дене (submit кезіндегі upstream_error немесе internal_error, insufficient_credits, budget_exceeded, too_many_inflight): ештеңе жасалмады және ақы алынбады, сондықтан сәтсіздікті қайтарудың орнына қайталап көру модельді қайта іске қосады.
  • Сол кілт, бірақ басқа дене: 409 idempotency_mismatch.
  • Кілттер оларды жіберген API кілтіне байланысты болады.

Файлдар қайда сақталады

Әр шығыс файл сұрау succeeded деп белгіленбес бұрын сақтау орнымызға көшіріледі, сондықтан outputs ішіндегі URL-дер өз хосттарымызда орналасады және оларға тікелей сілтеме жасай аласыз. Олардың қанша уақыт сақталатынын өзіңіз таңдайсыз:

Режим Ұзақтығы Бағасы
permanent (әдепкі) Өзіңіз жойғанға дейін Әр GB үшін айына 100 API кредиттері (0,10 $), API теңгерімінен күн сайын алынады
temporary 7 күн, кейін жойылады Тегін
  • Аккаунт параметрі жаңа сұраулар үшін қолданылады: бақылау тақтасындағы "Файлдарды мәңгілікке сақтау" ауыстырып-қосқышы немесе {"mode": "temporary"} мәнімен PATCH https://api.doitong.com/v1/account/storage. GET https://api.doitong.com/v1/account оны storage ішінде, сақтап отырған байттармен және айлық болжаммен көрсетеді.
  • Іске қосу кезіндегі ?storage=permanent|temporary (MCP run құралының storage аргументі) сол іске қосу үшін бұл параметрді қайта анықтайды.
  • Параметрді өзгерту бұрыннан бар файлдарға әсер етпейді; оларды DELETE /requests/{id}/files арқылы жойыңыз.
  • API теңгерімі сақтау ақысын төлеуге жетпесе, ақы алынбайды және электрондық хат аласыз: 30 күн ішінде теңгерімді толықтырыңыз, әйтпесе сақталған файлдар уақытша режимге ауысып, 7 күннен кейін жойылады.

Сирек жағдайда біздің көшірме жасау сәтсіз болса, жазбада "stored": false болады және URL бастапқы, қысқа мерзімді URL болып қалады: оны жақын арада жүктеп алыңыз.