Permintaan

Permintaan adalah satu panggilan ke satu model. Permintaan memiliki id (req_…), status, biaya dalam kredit API (1000 = 1 USD), dan, jika berhasil, file yang dihasilkan. Objek yang sama dikembalikan oleh setiap endpoint di bawah ini, untuk setiap model.

Menemukan model#

Katalog semua 1.496 model tersedia sebagai JSON publik (tidak memerlukan kunci):

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

Setiap baris memiliki id, name, lab, category, family, summary, tags, output_kind, docs_url, dan objek price (lihat Harga). GET https://api.doitong.com/v1/models/{model_id} menambahkan JSON Schema input dan output lengkap, nama parameter kanonis, aturan harga, dan contoh input. category atau mode yang tidak dikenal menghasilkan 400 invalid_parameter.

Menjalankan model#

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": "..."}'

• Body adalah input model, berupa objek JSON. Setiap halaman model mencantumkan parameternya.
• Input diperiksa sebelum biaya apa pun dibebankan. Input yang tidak valid menghasilkan 422 invalid_input dengan param yang bermasalah, dan tidak dikenai biaya.
• ?wait=N (hingga 20 detik) menahan panggilan hingga permintaan selesai atau waktunya habis.
• ?webhook_url=https://… mengirimkan POST bertanda tangan ke URL tersebut saat permintaan selesai (lihat Webhook).
• ?storage=permanent atau ?storage=temporary memilih berapa lama file output disimpan; jika tidak digunakan, pengaturan akun akan diterapkan (lihat Lokasi file).

Responsnya adalah 202 Accepted saat permintaan masih diproses, dan 200 OK jika selesai dalam waktu tunggu (atau jika merupakan pemutaran ulang, lihat di bawah). Header Location dan Doitong-Request-Id membawa URL dan id permintaan.

Status#

Permintaan yang berjalan lebih lama dari batas waktunya gagal dengan kode timeout dan dana dikembalikan: 15 menit untuk gambar, 60 menit untuk video, 30 menit untuk audio, dan semua jenis lainnya.

Objek permintaan#

{
  "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 sama untuk setiap model: satu entri per file yang dihasilkan dengan type (image, video, audio, file atau 3d), url pada penyimpanan kami, content_type, dan jika diketahui, file_size, width, height, duration.
• output adalah objek hasil milik model (field-nya tercantum di setiap halaman model) dengan URL yang sama.
• storage menjelaskan cara file disimpan: mode (permanent atau temporary), bytes yang disimpan, expires_at (saat file sementara dihapus, null untuk file permanen), dan expired (true setelah file dihapus).
• cost.credits adalah harga panggilan dalam kredit API (cost.usd dalam USD), cost.charged adalah jumlah yang didebit dari saldo API, dan cost.refunded adalah jumlah yang dikembalikan. Untuk model metered, cost.credits adalah maksimum yang ditahan di awal (cost.held); setelah eksekusi berhasil, cost.settled menunjukkan jumlah penggunaan, dan sisa maksimum berada di cost.refunded (lihat Ditagih berdasarkan penggunaan).
• Jika permintaan gagal, error berbentuk { "type": …, "code": …, "message": … }.

Membaca permintaan#

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

• ?wait=N (hingga 20 detik) melakukan long-poll: panggilan dikembalikan segera setelah permintaan final, atau setelah N detik dengan status saat ini. Melakukan loop dengan cara ini adalah cara paling sederhana untuk menunggu hasil.
• ?logs=1 menambahkan baris log kemajuan model (50 terakhir) sebagai logs.

Anda hanya dapat membaca permintaan dari akun Anda sendiri; id lain apa pun menghasilkan 404 request_not_found.

Mencantumkan permintaan#

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

Yang terbaru ditampilkan terlebih dahulu. limit bernilai 1 hingga 100 (bawaan 20), sedangkan status dan model berfungsi sebagai filter. Responsnya adalah { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }; teruskan cursor=<next_cursor> untuk halaman berikutnya.

Membatalkan permintaan#

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

• Dibatalkan sebelum model dimulai: status menjadi canceled, kredit API dikembalikan, dan Anda menerima 200.
• Sudah dalam proses pembuatan: pembatalan diteruskan dan Anda menerima 202 dengan "cancel_requested": true. Jika model tetap selesai, permintaan berhasil seperti biasa dan ditagih.
• Sudah final: 409 not_cancelable (permintaan yang sudah canceled cukup mengembalikan 200).

Menghapus file permintaan#

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

Segera menghapus salinan file output permintaan kami dan menghentikan biaya penyimpanannya. Responsnya adalah objek permintaan dengan storage.expired: true; URL-nya tetap berada dalam catatan, tetapi tidak lagi berfungsi. Pemanggilan ulang tidak mengubah apa pun (200). Permintaan yang masih queued atau running belum memiliki file: 409 request_active. Memerlukan models:run.

Idempotensi: mencoba ulang tanpa membayar dua kali#

Jaringan dapat gagal. Untuk mencoba ulang eksekusi dengan aman, kirim header Idempotency-Key (string apa pun hingga 255 karakter, unik per operasi, misalnya id pesanan Anda sendiri):

• Kunci dan body yang sama seperti sebelumnya: Anda menerima kembali permintaan asli (200, header Idempotent-Replayed: true), dan tidak ada biaya tambahan.
• Kunci dan body yang sama setelah eksekusi gagal sebelum mencapai model (upstream_error atau internal_error saat pengiriman, insufficient_credits, budget_exceeded, too_many_inflight): tidak ada yang dihasilkan dan tidak ada biaya, sehingga percobaan ulang menjalankan model lagi alih-alih mengembalikan kegagalan.
• Kunci yang sama dengan body berbeda: 409 idempotency_mismatch.
• Kunci dibatasi pada kunci API yang mengirimkannya.

Lokasi file#

Setiap file output disalin ke penyimpanan kami sebelum permintaan ditandai succeeded, sehingga URL dalam outputs berada di host kami sendiri dan dapat ditautkan langsung. Anda dapat memilih berapa lama file tersebut disimpan:

• Pengaturan akun menentukan perilaku untuk permintaan baru: tombol "Simpan file selamanya" di dasbor, atau PATCH https://api.doitong.com/v1/account/storage dengan {"mode": "temporary"}. GET https://api.doitong.com/v1/account menampilkannya di bawah storage, bersama byte yang Anda simpan dan perkiraan bulanan.
• ?storage=permanent|temporary pada eksekusi (argumen storage dari tool MCP run) menggantikan pengaturan untuk eksekusi tersebut.
• Mengubah pengaturan tidak pernah memengaruhi file yang sudah Anda miliki; hapus file tersebut dengan DELETE /requests/{id}/files.
• Jika saldo API tidak dapat membayar penyimpanan, tidak ada biaya yang dikenakan dan Anda menerima email: isi ulang dalam 30 hari, atau file yang disimpan menjadi sementara dan dihapus 7 hari kemudian.

Dalam kasus yang jarang terjadi ketika penyalinan kami gagal, entri memiliki "stored": false dan URL-nya adalah URL asli yang berumur pendek: segera unduh.