Yêu cầu

Một yêu cầu là một lần gọi một mô hình. Yêu cầu có id (req_…), trạng thái, chi phí tính bằng tín dụng API (1000 = 1 USD) và, khi thành công, các tệp được tạo. Cùng một đối tượng được trả về từ mọi điểm cuối bên dưới, với mọi mô hình.

Tìm mô hình#

Danh mục gồm tất cả 1.496 mô hình là JSON công khai (không cần khóa):

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

Mỗi hàng có id, name, lab, category, family, summary, tags, output_kind, docs_url và một đối tượng price (xem Định giá). GET https://api.doitong.ru/v1/models/{model_id} bổ sung JSON Schema đầy đủ cho đầu vào và đầu ra, tên tham số chuẩn, quy tắc giá và một đầu vào mẫu. category hoặc mode không hợp lệ sẽ trả về 400 invalid_parameter.

Chạy mô hình#

curl -X POST "https://api.doitong.ru/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": "..."}'

• Phần thân là đầu vào của mô hình, một đối tượng JSON. Trang của từng mô hình liệt kê các tham số.
• Đầu vào được kiểm tra trước khi tính phí. Đầu vào không hợp lệ trả về 422 invalid_input cùng param gây lỗi và không tốn phí.
• ?wait=N (tối đa 20 giây) giữ cuộc gọi cho đến khi yêu cầu hoàn tất hoặc hết thời gian.
• ?webhook_url=https://… gửi một POST có chữ ký đến URL đó khi yêu cầu hoàn tất (xem Webhook).
• ?storage=permanent hoặc ?storage=temporary chọn thời gian giữ các tệp đầu ra; nếu không có, cài đặt tài khoản sẽ được áp dụng (xem Nơi lưu tệp).

Phản hồi là 202 Accepted khi yêu cầu vẫn đang được xử lý và 200 OK khi yêu cầu hoàn tất trong thời gian chờ (hoặc khi đây là lần phát lại, xem bên dưới). Các header Location và Doitong-Request-Id chứa URL và id của yêu cầu.

Trạng thái#

Yêu cầu chạy quá giới hạn thời gian sẽ thất bại với mã timeout và được hoàn tiền: 15 phút cho hình ảnh, 60 phút cho video, 30 phút cho âm thanh và mọi trường hợp khác.

Đối tượng yêu cầu#

{
  "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.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}

• outputs giống nhau với mọi mô hình: mỗi tệp được tạo có một mục gồm type (image, video, audio, file hoặc 3d), url trên hệ thống lưu trữ của chúng tôi, content_type và, khi biết, file_size, width, height, duration.
• output là đối tượng kết quả riêng của mô hình (các trường được liệt kê trên trang của từng mô hình), với cùng các URL.
• storage cho biết cách giữ các tệp: mode (permanent hoặc temporary), số bytes đã lưu, expires_at (thời điểm tệp tạm thời bị xóa, null đối với tệp vĩnh viễn) và expired (true khi các tệp đã biến mất).
• cost.credits là giá của cuộc gọi tính bằng tín dụng API (cost.usd tính bằng USD), cost.charged là số tiền đã trừ khỏi số dư API, cost.refunded là số tiền được hoàn lại. Với mô hình metered, cost.credits là mức tối đa được giữ lúc bắt đầu (cost.held); khi lần chạy thành công, cost.settled cho biết mức sử dụng thực tế và phần còn lại của mức tối đa nằm trong cost.refunded (xem Tính phí theo mức sử dụng).
• Khi yêu cầu thất bại, error có dạng { "type": …, "code": …, "message": … }.

Đọc một yêu cầu#

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

• ?wait=N (tối đa 20 giây) thực hiện long-poll: cuộc gọi trả về ngay khi yêu cầu có trạng thái cuối cùng, hoặc sau N giây với trạng thái hiện tại. Lặp cách này là phương pháp đơn giản nhất để chờ kết quả.
• ?logs=1 thêm các dòng nhật ký tiến trình của mô hình (50 dòng cuối) dưới dạng logs.

Bạn chỉ có thể đọc các yêu cầu thuộc tài khoản của mình; mọi id khác trả về 404 request_not_found.

Liệt kê yêu cầu#

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

Mới nhất trước. limit từ 1 đến 100 (mặc định 20), status và model dùng để lọc. Phản hồi có dạng { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }; truyền cursor=<next_cursor> để lấy trang tiếp theo.

Hủy một yêu cầu#

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

• Đã hủy trước khi mô hình bắt đầu: trạng thái trở thành canceled, tín dụng API được hoàn tiền và bạn nhận 200.
• Đang tạo kết quả: yêu cầu hủy được chuyển tiếp và bạn nhận 202 với "cancel_requested": true. Nếu mô hình vẫn hoàn tất, yêu cầu thành công bình thường và bị tính phí.
• Đã ở trạng thái cuối: 409 not_cancelable (yêu cầu đã canceled chỉ đơn giản trả về 200).

Xóa các tệp của một yêu cầu#

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

Xóa ngay các bản sao tệp đầu ra của yêu cầu trên hệ thống của chúng tôi và dừng phí lưu trữ. Phản hồi là đối tượng yêu cầu với storage.expired: true; URL vẫn nằm trong bản ghi nhưng không còn hoạt động. Gọi lại không thay đổi gì (200). Yêu cầu vẫn đang queued hoặc running chưa có tệp: 409 request_active. Cần models:run.

Tính bất biến: thử lại mà không trả phí hai lần#

Mạng có thể gặp lỗi. Để thử lại an toàn, hãy gửi header Idempotency-Key (bất kỳ chuỗi nào tối đa 255 ký tự, duy nhất cho mỗi thao tác, ví dụ id đơn hàng của bạn):

• Cùng khóa và cùng phần thân như trước: bạn nhận lại yêu cầu ban đầu (200, header Idempotent-Replayed: true) và không bị tính phí lần nữa.
• Cùng khóa và phần thân sau một lần chạy thất bại trước khi đến mô hình (upstream_error hoặc internal_error khi gửi, insufficient_credits, budget_exceeded, too_many_inflight): không có gì được tạo và không bị tính phí, nên lần thử lại sẽ chạy mô hình thay vì trả về lỗi.
• Cùng khóa nhưng phần thân khác: 409 idempotency_mismatch.
• Khóa được giới hạn trong khóa API đã gửi chúng.

Nơi lưu tệp#

Mỗi tệp đầu ra được sao chép vào hệ thống lưu trữ trước khi yêu cầu được đánh dấu succeeded, vì vậy các URL trong outputs nằm trên máy chủ của chúng tôi và bạn có thể liên kết trực tiếp đến chúng. Bạn tự chọn thời gian lưu:

• Cài đặt tài khoản quyết định cho các yêu cầu mới: công tắc "Lưu tệp vĩnh viễn" trong bảng điều khiển, hoặc PATCH https://api.doitong.ru/v1/account/storage với {"mode": "temporary"}. GET https://api.doitong.ru/v1/account hiển thị cài đặt này trong storage, cùng số byte bạn giữ và ước tính hàng tháng.
• ?storage=permanent|temporary trong một lần chạy (đối số storage của công cụ MCP run) sẽ ghi đè cài đặt cho lần chạy đó.
• Thay đổi cài đặt không bao giờ tác động đến các tệp bạn đã có; hãy xóa chúng bằng DELETE /requests/{id}/files.
• Khi số dư API không đủ trả phí lưu trữ, không có khoản phí nào được tính và bạn nhận email: hãy nạp tiền trong 30 ngày, nếu không các tệp đang giữ sẽ trở thành tạm thời và bị xóa sau 7 ngày.

Trong trường hợp hiếm gặp khi bản sao của chúng tôi bị lỗi, mục đó có "stored": false và URL là URL gốc có thời hạn ngắn: hãy tải xuống sớm.