# Tús tapa

Rith do chéad ghiniúint i gceann cúpla nóiméad. Glacann na samhlacha 1,496 go léir leis an gcineál céanna iarratais agus seolann siad an
réad iarratais céanna ar ais, le haghaidh íomhánna, físeáin agus fuaime: foghlaim é uair amháin anseo.

> [!NOTE]
> BunURL `https://api.doitong.com/v1`. Seolann gach glao `Authorization: Bearer <your key>`, agus oibríonn an eochair chéanna don
> API HTTP agus don fhreastalaí MCP.

## 1. Faigh eochair API

Cruthaigh eochair ag [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys) agus coinnigh in athróg
chomhshaoil í: taispeántar í uair amháin בלבד. Féadfaidh a bhuiséad féin a bheith ag gach eochair, ionas gur féidir leat ceann a thabhairt do ghníomhaire
gan an cuntas iomlán a chur i mbaol. Seolann `GET /account` iarmhéid do API ar ais.

```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())
```

Íoctar ritheanna as **iarmhéid API** do chuntais i gcreidmheasanna API: 1,000 gcreidmheas API = $1, agus cosnaíonn gach samhail
praghas a déantóra go beacht. Déan breisiú ag [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance).

## 2. Faigh meastachán, ansin rith

Glacann `POST /quote/{model_id}` leis an JSON ionchuir agus seolann sé an praghas beacht ar ais. Níl eochair de dhíth air agus níl aon chostas air.
Cosnaíonn an t-ionchur céanna a rith an méid sin go díreach: is é an meastachán an muirear. (Is eisceacht í samhail a ghearrtar de réir úsáide: is é a
meastachán an t-uasmhéid a d’fhéadfadh costas a bheith ar an rith, agus aisíoctar an chuid nár úsáideadh tar éis an rithe.)

```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 · meastachán
{
  "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"
}
```

Seol an corp céanna ansin chuig `POST /run/{model_id}`. Cuir `?wait=20` leis chun an nasc a choinneáil ar feadh suas le 20 soicind: seolann samhail thapa an
 toradh críochnaithe ar ais i dturas líonra amháin. Seol ceanntásc `Idempotency-Key` ionas nach rithfear (ná nach ngearrfar táille ar) atriail faoi dhó.

```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)
```

Is réad iarratais é an freagra:

```json 200 OK · iarratas
{
  "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. Lean an stádas

Má tá an tsamhail fós ag obair nuair a chríochnaíonn an fanacht, gheobhaidh tú `202 Accepted` le `id` an iarratais agus a `status` reatha. Téann gach iarratas tríd an
saolré chéanna:

Saolré an iarratais: `queued` → `running` → `succeeded` | `failed` | `canceled` (críochnaitheach; aisíoctar cinn a theip orthu agus a cuireadh ar ceal).

Léigh an t-iarratas arís lena aitheantas. Oibríonn `?wait=20` anseo freisin, mar sin is leor lúb shimplí:

```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)
```

Nuair is é `succeeded` an `status`, tá naisc chuig na comhaid inár stóráil in `outputs[].url`. Má theip ar an iarratas (`failed`) nó má cuireadh ar ceal é
(`canceled`), aisíoctar a chreidmheasanna API go huathoibríoch agus insíonn `error` cén fáth. Cuir aon rud atá fós `queued` nó
`running` ar ceal:

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

I gcás jabanna físeáin fada, is féidir leat gan vótaíocht a dhéanamh agus `webhook_url` a thabhairt ina ionad (féach [Crúcaí gréasáin](https://doitong.com/developers/docs/webhooks)).

## 4. Comhaid

Tabhair URL poiblí ar bith mar ionchur, nó iarr URL uaslódála le `POST /files`, cuir an comhad chuige le `PUT` agus úsáid an
`file_url` a sheoltar ar ais (féach [Comhaid](https://doitong.com/developers/docs/files)). Liostaíonn iarratas ar éirigh leis a thorthaí in `outputs[]` le
type, content type agus, nuair is eol iad, toisí agus fad.

```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]
> **Comhaid coinnithe go deo, nó 7 lá saor in aisce: do rogha féin.** Cóipeáiltear comhaid aschuir chuig ár
> stóráil sula n-éiríonn le hiarratas. De réir réamhshocraithe, fanann siad go dtí go scriosann tú iad (100 creidmheasanna API
> in aghaidh GB in aghaidh na míosa); múch "Coinnigh comhaid go deo" sa deais, nó tabhair `?storage=temporary`, chun iad a choinneáil
> ar feadh 7 lá saor in aisce (féach [Comhaid](https://doitong.com/developers/docs/files#storage)).

## Earráidí

Teipeann ar gach samhail ar an mbealach céanna: clúdach amháin le `type`, `code` cruinn, an `param` is cúis leis agus gach fadhb in
`details`, ionas gur féidir le gníomhaire an t-iarratas a cheartú gan próis a léamh. Ní ghearrtar aon táille ar iarratas neamhbhailí.

```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"
  }
}
```

Tá gach cineál agus cód liostaithe in [Earráidí](https://doitong.com/developers/docs/errors).

## Praghsáil

Tá praghsanna in USD agus i gcreidmheasanna API agus taispeántar iad ar gach leathanach samhla sula ritheann tú. Iompraíonn gach iarratas `cost` le
`credits`, `usd`, `charged` agus `refunded`. Gearrtar táille ar rith nuair a ghlactar leis; aisíoctar iarratais `failed` agus `canceled`
go huathoibríoch. Gearrtar praghas beacht ó ionchur ar roinnt samhlacha, gearrtar cuid eile de réir fhad nó mhéid na gcomhad a sheolann tú,
agus gearrann samhlacha eile *praghas measta in aghaidh an rithe*: cibé bealach, is é an meastachán an méid a íocann tú. Gearrtar táille de réir úsáide ar
roinnt samhlacha (samhlacha teanga agus físe, guth, uirlisí ama próiseála): is é an meastachán an t-uasmhéid a d’fhéadfadh costas a bheith ar an rith, agus
aisíoctar go huathoibríoch an chuid nár úsáideadh. Féach [Praghsáil](https://doitong.com/developers/docs/pricing).

## MCP agus gníomhairí AI

Ceangail aon chliant MCP le `https://api.doitong.com/v1/mcp` leis an eochair Bearer chéanna. Is féidir le do ghníomhaire an chatalóg a chuardach, meastacháin a fháil agus
samhlacha a rith, agus gach leathanach doiciméad a léamh mar Markdown.

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

## Na chéad chéimeanna eile

- Brabhsáil [na samhlacha go léir](https://doitong.com/developers/models). Tá tógálaí iarratas ar gach leathanach a scríobhann an cód duit.
- Foghlaim saolré an iarratais: [Iarratais](https://doitong.com/developers/docs/requests).
- Úsáid na hainmneacha paraiméadar céanna ar gach samhail: [Paraiméadair](https://doitong.com/developers/docs/parameters).
- Ag obair le gníomhaire códúcháin AI? Tabhair [https://doitong.com/developers/llms.txt](https://doitong.com/developers/llms.txt) dó nó ceangail an [freastalaí MCP](https://doitong.com/developers/docs/mcp).