# Mabilisang pagsisimula

Patakbuhin ang iyong unang pagbuo sa loob ng ilang minuto. Pare-parehong uri ng kahilingan ang tinatanggap ng lahat ng 1,496 modelo at pare-parehong kahilingan object ang ibinabalik para sa larawan, video at audio: matutuhan ito nang isang beses dito.

> [!NOTE]
> Base URL `https://api.doitong.com/v1`. Sa bawat tawag, ipinapadala ang `Authorization: Bearer <your key>`, at gumagana ang parehong key para sa HTTP API at MCP server.

## 1. Kumuha ng API key

Gumawa ng key sa [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys) at itago ito sa isang environment variable: isang beses lang itong ipinapakita. Maaaring magkaroon ng sariling badyet ang bawat key, kaya maaari kang magbigay ng isa sa isang agent nang hindi nalalagay sa panganib ang buong account. Ibinabalik ng `GET /account` ang iyong balanse sa API.

```bash
export DOITONG_API_KEY="doitong_..."

curl "https://api.doitong.com/v1/account" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```
```javascript
const res = await fetch("https://api.doitong.com/v1/account", {
  headers: { Authorization: `Bearer ${process.env.DOITONG_API_KEY}` },
});

console.log(await res.json());
```
```python
import os
import requests

r = requests.get(
    "https://api.doitong.com/v1/account",
    headers={"Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}"},
)
print(r.json())
```

Binabayaran ang mga run mula sa **API balanse** ng iyong account sa kredito ng API: 1,000 kredito ng API = $1, at eksaktong presyo ng gumawa nito ang halaga ng bawat modelo. Magdagdag ng balanse sa [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance).

## 2. Kumuha muna ng quote, saka magpatakbo

Tinatanggap ng `POST /quote/{model_id}` ang input JSON at ibinabalik ang eksaktong presyo. Hindi nito kailangan ng key at walang gastos. Ang pagpapatakbo sa parehong input ay eksaktong ganoon ang halaga: ang quote ang singil. (Ang modelong sinisingil batay sa paggamit ang eksepsiyon: ang quote nito ang pinakamalaking maaaring halaga ng run, at ibinabalik ang hindi nagamit pagkatapos ng run.)

```bash
curl -X POST "https://api.doitong.com/v1/quote/kling-video/v3/pro/image-to-video" \
  -H "Content-Type: application/json" \
  -d '{"image": "https://example.com/fox.jpg", "duration": 5, "generate_audio": true}'
```
```javascript
const res = await fetch("https://api.doitong.com/v1/quote/kling-video/v3/pro/image-to-video", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ image: "https://example.com/fox.jpg", duration: 5, generate_audio: true }),
});

const quote = await res.json();
console.log(quote.credits, quote.usd); // 840 "0.84"
```
```python
import requests

r = requests.post(
    "https://api.doitong.com/v1/quote/kling-video/v3/pro/image-to-video",
    json={"image": "https://example.com/fox.jpg", "duration": 5, "generate_audio": True},
)
print(r.json()["credits"], r.json()["usd"])  # 840 0.84
```

```json 200 OK · quote
{
  "object": "quote",
  "model": "kling-video/v3/pro/image-to-video",
  "credits": 840,
  "usd": "0.84",
  "unit": "second",
  "quantity": 5,
  "unit_credits": 168,
  "mode": "exact",
  "breakdown": "5 s × 168 API credits"
}
```

Pagkatapos, ipadala ang parehong body sa `POST /run/{model_id}`. Idagdag ang `?wait=20` upang panatilihing bukas ang koneksiyon nang hanggang 20 segundo: ibinabalik ng mabilis na modelo ang natapos na resulta sa isang round trip. Magpadala ng `Idempotency-Key` header upang hindi kailanman dalawang beses mapatakbo o masingil ang isang retry.

```bash
curl -X POST "https://api.doitong.com/v1/run/flux/schnell?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lighthouse-001" \
  -d '{"prompt": "A lighthouse on a rocky coast at dusk, warm light in the window"}'
```
```javascript
const res = await fetch("https://api.doitong.com/v1/run/flux/schnell?wait=20", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DOITONG_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "lighthouse-001",
  },
  body: JSON.stringify({ prompt: "A lighthouse on a rocky coast at dusk, warm light in the window" }),
});

const request = await res.json();
console.log(request.status, request.outputs[0]?.url);
```
```python
import os
import requests

r = requests.post(
    "https://api.doitong.com/v1/run/flux/schnell",
    params={"wait": 20},
    headers={
        "Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}",
        "Idempotency-Key": "lighthouse-001",
    },
    json={"prompt": "A lighthouse on a rocky coast at dusk, warm light in the window"},
)
request = r.json()
print(request["status"], request["outputs"][0]["url"] if request["outputs"] else None)
```

Ang response ay isang kahilingan object:

```json 200 OK · kahilingan
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg", "width": 1024, "height": 768, "stored": true }
  ],
  "error": null
}
```

## 3. Subaybayan ang status

Kung gumagana pa rin ang modelo kapag natapos ang paghihintay, makakakuha ka ng `202 Accepted` kasama ang `id` ng kahilingan at kasalukuyan nitong `status`. Dumaraan ang bawat kahilingan sa parehong lifecycle:

Lifecycle ng kahilingan: `queued` → `running` → `succeeded` | `failed` | `canceled` (final; nire-refund ang mga nabigo at nakansela).

Basahin muli ang kahilingan gamit ang id nito. Gumagana rin dito ang `?wait=20`, kaya sapat na ang simpleng loop:

```bash
curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```
```javascript
const headers = { Authorization: `Bearer ${process.env.DOITONG_API_KEY}` };
let request = await (await fetch("https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20", { headers })).json();

while (request.status === "queued" || request.status === "running") {
  const res = await fetch(`https://api.doitong.com/v1/requests/${request.id}?wait=20`, { headers });
  request = await res.json();
}

console.log(request.status, request.outputs[0]?.url);
```
```python
import os
import requests

headers = {"Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}"}
request = {"id": "req_8k2m4q7x1z9c3v5b6n0p2r4t", "status": "queued"}

while request["status"] in ("queued", "running"):
    request = requests.get(
        f"https://api.doitong.com/v1/requests/{request['id']}",
        params={"wait": 20},
        headers=headers,
    ).json()

print(request["status"], request["outputs"][0]["url"] if request["outputs"] else None)
```

Kapag `status` ay `succeeded`, naglalaman ang `outputs[].url` ng mga link sa mga file sa aming storage. Kung ang kahilingan ay `failed` o `canceled`, awtomatikong ibinabalik ang kredito ng API nito at ipinapaliwanag ng `error` ang dahilan. Kanselahin ang anumang `queued` o `running`:

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

Para sa mahahabang video job, maaari mong laktawan ang polling at sa halip ay magpasa ng `webhook_url` (tingnan ang [Webhooks](https://doitong.com/developers/docs/webhooks)).

## 4. Mga file

Magpasa ng anumang pampublikong URL bilang input, o humingi sa `POST /files` ng upload URL, i-`PUT` ang file doon at gamitin ang ibinalik na `file_url` (tingnan ang [Files](https://doitong.com/developers/docs/files)). Inililista ng isang matagumpay na kahilingan ang mga resulta nito sa `outputs[]` kasama ang type, content type at, kapag alam, mga dimensiyon at tagal.

```bash
curl -X POST "https://api.doitong.com/v1/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "fox.jpg", "content_type": "image/jpeg", "size": 482113}'
```

> [!TIP]
> **Walang hanggan ang pagpapanatili ng mga file, o 7 araw nang libre: ikaw ang pumili.** Kinokopya ang mga output file sa aming storage bago maging matagumpay ang isang kahilingan. Bilang default, nananatili ang mga ito hanggang burahin mo (100 kredito ng API bawat GB bawat buwan); i-off ang switch na "Itago ang mga file habambuhay" sa dashboard, o ipasa ang `?storage=temporary`, upang manatili ang mga ito nang 7 araw nang libre (tingnan ang [Files](https://doitong.com/developers/docs/files#storage)).

## Mga error

Pareho ang paraan ng pagkabigo ng bawat modelo: isang envelope na may `type`, eksaktong `code`, problemadong `param` at bawat problema sa `details`, upang maayos ng isang agent ang kahilingan nang hindi nagbabasa ng paliwanag. Walang sinisingil para sa invalid na kahilingan.

```json 422 Unprocessable Entity
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}
```

Nakalista ang bawat type at code sa [Errors](https://doitong.com/developers/docs/errors).

## Pagpepresyo

Nasa USD at kredito ng API ang mga presyo at ipinapakita sa bawat pahina ng modelo bago ka magpatakbo. May `cost` ang bawat kahilingan na may `credits`, `usd`, `charged` at `refunded`. Sisingilin ang run kapag tinanggap ito; awtomatikong nire-refund ang mga `failed` at `canceled` na kahilingan. Eksaktong batay sa input ang presyo ng ilang modelo, batay sa haba o laki ng mga file na ipinapadala mo ang iba, at ang iba naman ay naniningil ng *estimated price per run*: sa alinmang paraan, ang quote ang iyong babayaran. Ang ilang modelo (mga modelo ng wika at vision, voice, at mga tool na nakabatay sa oras ng pagproseso) ay *sinisingil batay sa paggamit*: ang quote ang pinakamalaking maaaring halaga ng run, at awtomatikong nire-refund ang bahaging hindi nagamit ng run. Tingnan ang [Pricing](https://doitong.com/developers/docs/pricing).

## MCP at mga AI agent

Ikonekta ang anumang MCP client sa `https://api.doitong.com/v1/mcp` gamit ang parehong Bearer key. Maaaring maghanap ang iyong agent sa catalog, kumuha ng quote at magpatakbo ng mga modelo, at basahin ang bawat pahina ng dokumentasyon bilang Markdown.

```bash Claude Code
claude mcp add --transport http doitong-models https://api.doitong.com/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

## Mga susunod na hakbang

- I-browse ang [lahat ng modelo](https://doitong.com/developers/models). May kahilingan builder ang bawat pahina na sumusulat ng code para sa iyo.
- Alamin ang lifecycle ng kahilingan: [Requests](https://doitong.com/developers/docs/requests).
- Gamitin ang parehong pangalan ng parameter sa bawat modelo: [Parameters](https://doitong.com/developers/docs/parameters).
- Gumagamit ka ba ng AI coding agent? Ibigay rito ang [https://doitong.com/developers/llms.txt](https://doitong.com/developers/llms.txt) o ikonekta ang [MCP server](https://doitong.com/developers/docs/mcp).