# Cosmos 3 Super API

> Gineadh teacsa-gu-ìomhaigh le leudachadh prompt agus modh roghainneil coimeas thagraichean agentach

A’ cruthachadh 1 gu 4 ìomhaighean bho `prompt` le suas ri 4096 caractaran. Tha oirean `image_size` air an cuingealachadh ri 512-1280 px. Bidh `enable_agentic_generation` a’ dèanamh grunn thagraichean agus ag ùrachadh a’ phrompt eadar chuairtean, le suas ri 3 ath-aithrisean. Tha `negative_prompt`, `guidance_scale` suas ri 20, `num_inference_steps` suas ri 50, agus toradh jpeg no png rim faighinn cuideachd.

- Model id: `nvidia/cosmos-3-super/text-to-image`
- Made by: NVIDIA
- Category: Text to Image
- Output: image
- Price per run: from $0.04 / run of output image (cheapest run $0.04 (40 API credits))
- Run: `POST https://api.doitong.ru/v1/run/nvidia/cosmos-3-super/text-to-image`
- Quote: `POST https://api.doitong.ru/v1/quote/nvidia/cosmos-3-super/text-to-image`
- Docs page: https://doitong.com/gd/developers/models/nvidia/cosmos-3-super/text-to-image

## Pricing

Price: **from $0.04 / run of output image** (the lowest tier; the quote prices your exact input). Price per run: the input files are measured before the run (length, resolution, frame rate). The quote measures the same files and is exactly what the run charges.

The full example input below costs $0.04 = 40 API credits (1 run × $0.04).

Prices are the upstream price in USD, paid from the API balance in API credits (1000 API credits = 1 USD). `POST https://api.doitong.ru/v1/quote/nvidia/cosmos-3-super/text-to-image` with the same JSON body returns the exact price for that input; the quote is exactly what a run charges. Invalid input is never charged and failed or canceled requests are refunded automatically.

## Input parameters

Send either the canonical name or the native field name (not both). Canonical names are the same across models.

| Parameter | Canonical name | Type | Required | Default | Allowed values / range | Description |
|---|---|---|---|---|---|---|
| `prompt` |  | string | yes |  | 1 – 4096 characters | Tuairisgeul teacsa air an ìomhaigh às-chuir a thathar ag iarraidh. |
| `negative_prompt` |  | string | no | `` | ≤ 1024 characters | Stiùireadh àicheil a chomharraicheas dathan, nithean no nithean fuadain nach eileas ag iarraidh airson an seachnadh ann an gineadh. |
| `enable_prompt_expansion` |  | boolean | no | `false` |  | Leasachadh prompt ro ghineadh tro OpenRouter, a’ cruthachadh an riochdachadh dùmhail structaraichte JSON a chaidh a chleachdadh airson Cosmos3 a thrèanadh nuair a tha e an comas. Ma dh’fhàillig an leasachadh, leanaidh gineadh na h-ìomhaighe le prompt gun atharrachadh. |
| `enable_agentic_generation` |  | boolean | no | `false` |  | Lùb fèin-obrachail airson prompt ath-mhìneachadh, ag amas air cumail nas dlùithe ris an iarrtas thùsail. Bidh gach cuairt a’ gineadh grunn thagraichean ìomhaighe agus gan coimeas, le ath-sgrùdaidhean prompt eadar na cuairtean. |
| `agentic_max_iterations` |  | integer | no | `2` | 1 – 3 | Crìoch nan cuairtean ath-mhìneachaidh airson gineadh le modh àidseantach an comas. |
| `agentic_samples_per_iteration` |  | integer | no | `2` | 1 – 3 | Àireamh thagraichean ìomhaighe gach tionndaidh airson an lùib àidseantach, a’ dearbhadh cia mheud ìomhaigh a bhios a’ farpais ann am measadh mus tèid an fheadhainn as fheàrr air adhart gu ath-sgrìobhadh a’ phrompt. |
| `agentic_early_stop` |  | boolean | no | `true` |  | Smachd stad tràth a tha a’ meas co-dhealbhadh làidir eadar ìomhaigh agus prompt mar leòr airson crìochnachadh gun tuilleadh thionndaidhean. |
| `image_size` |  | object {width, height} \| enum (string) | no | `square_hd` | `square_hd`, `square`, `portrait_4_3`, `portrait_16_9`, `landscape_4_3`, `landscape_16_9` | Suidhich meudan na h-ìomhaighe às-chuir; bidh cuingealachadh a’ cumail gach oir eadar 512 agus 1280px, le faid nan oirean cuibhrichte ri iomadan de 16. |
| `num_inference_steps` |  | integer | no | `28` | 1 – 50 | Àireamh cheumannan dì-fhuaimidh, far a bheil barrachd ùine giullachd air a malairt airson càileachd nas fheàrr mar a bhios an àireamh ag èirigh. |
| `guidance_scale` |  | number | no | `4` | 0 – 20 | Neart stiùiridh gun chlasadair. |
| `num_images` | `num_outputs` | integer | no | `1` | 1 – 4 | Àireamh nan ìomhaighean a chaidh iarraidh airson gineadh. |
| `seed` |  | integer \| null | no |  |  | Sìol airson gineadh ìomhaighe ath-aithriseach. Bidh an ìomhaigh às-chuir gun atharrachadh thar ruith mura h-atharraich an sìol, am prompt no dreach a’ mhodail. |
| `enable_safety_checker` |  | boolean | no | `true` |  | Tionndadh measaidh susbaint a tha a’ còmhdach an dà chuid in-chur prompt agus às-chur ìomhaighe. Feumaidh cunntasan ùghdarras airson measaidh a sheachnadh; air neo, tha sgrùdaidhean riatanach ge bith dè an suidheachadh. Thèid ìomhaigh dhì-shàbhailte sam bith a chur an àite ìomhaigh dhubh. |
| `output_format` |  | enum (string) | no | `jpeg` | `jpeg`, `png` | Cruth faidhle na h-ìomhaigh a thig às. |

## Example input

Required parameters only:

```json
{
  "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
}
```

A fuller example:

```json
{
  "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
}
```

## Run it

Set `DOITONG_API_KEY` to a key from https://doitong.com/developers/dashboard#keys. `?wait=20` returns the finished request in the same call when it is ready within 20 seconds; otherwise poll `GET /requests/{id}` (it also accepts `?wait=`), or pass `webhook_url`.

### curl

```bash
# Run the model; wait up to 20 s for the finished result in the same call
curl -X POST "https://api.doitong.ru/v1/run/nvidia/cosmos-3-super/text-to-image?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  }'

# Still "queued" or "running"? Poll with the id from the response:
curl "https://api.doitong.ru/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.ru/v1";
const headers = {
  "Authorization": "Bearer " + process.env.DOITONG_API_KEY,
  "Content-Type": "application/json",
};

// Run the model; wait up to 20 s for the finished result in the same call
let res = await fetch(API + "/run/nvidia/cosmos-3-super/text-to-image?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  }),
});
let request = await res.json();
if (!res.ok) throw new Error(request.error.code + ": " + request.error.message);

// Not finished yet: long-poll until it is
while (request.status === "queued" || request.status === "running") {
  res = await fetch(API + "/requests/" + request.id + "?wait=20", { headers });
  request = await res.json();
}
if (request.status !== "succeeded") throw new Error(JSON.stringify(request.error));
console.log(request.outputs.map((o) => o.url), request.cost.credits + " API credits ($" + request.cost.usd + ")");
```

### Python

```python
import os
import requests

API = "https://api.doitong.ru/v1"
headers = {"Authorization": "Bearer " + os.environ["DOITONG_API_KEY"]}

payload = {
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/nvidia/cosmos-3-super/text-to-image", params={"wait": 20}, json=payload, headers=headers)
request = r.json()
if not r.ok:
    raise RuntimeError(request["error"]["code"] + ": " + request["error"]["message"])

# Not finished yet: long-poll until it is
while request["status"] in ("queued", "running"):
    request = requests.get(API + "/requests/" + request["id"], params={"wait": 20}, headers=headers).json()
if request["status"] != "succeeded":
    raise RuntimeError(request["error"])
print([o["url"] for o in request["outputs"]], request["cost"]["credits"], "API credits", "$" + request["cost"]["usd"])
```

### MCP

The MCP server at `https://api.doitong.ru/v1/mcp` exposes the tools `search_models`, `get_model`, `quote`, `run`, `get_request`, `cancel_request`, `list_requests`, `create_upload` and `get_account`. A `run` call for this model:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run",
    "arguments": {
      "model_id": "nvidia/cosmos-3-super/text-to-image",
      "input": {
        "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
      },
      "wait_seconds": 20
    }
  }
}
```

## Response

Every call returns a request object. `status` is one of `queued`, `running`, `succeeded`, `failed`, `canceled`. `outputs` lists the generated files with URLs on our storage (kept forever, or 7 days with `?storage=temporary`; `storage` says which); `output` is the model's own result object with the same URLs.

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "nvidia/cosmos-3-super/text-to-image",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:02Z",
  "completed_at": "2026-10-20T12:00:09Z",
  "queue_position": null,
  "cost": {
    "credits": 40,
    "usd": "0.04",
    "charged": 40,
    "refunded": 0
  },
  "input": {
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  },
  "output": {
    "images": [
      {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200,
        "width": 1024,
        "height": 768
      }
    ],
    "seed": 42,
    "has_nsfw_concepts": [
      false
    ]
  },
  "outputs": [
    {
      "type": "image",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_size": 1843200,
      "width": 1024,
      "height": 768,
      "stored": true
    }
  ],
  "error": null,
  "metrics": {
    "inference_seconds": 6.8
  },
  "urls": {
    "self": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `images` | array of object {url, content_type, file_name, file_size, width, height} | Ìomhaighean a chaidh a chruthachadh leis a’ mhodail. |
| `seed` | integer | Luach sìl a chaidh a chur an sàs rè gineadh. |
| `has_nsfw_concepts` | array of boolean | Inbhe bratach an t-sgrùdaiche sàbhailteachd airson gach ìomhaigh ghinte. |

## Related models

- [Cosmos 3 Super Image to Video](https://doitong.com/developers/models/nvidia/cosmos-3-super/image-to-video.md) (`nvidia/cosmos-3-super/image-to-video`): from $0.05 / second of output video
- [FLUX.1 \[dev\]](https://doitong.com/developers/models/flux/dev.md) (`flux/dev`): $0.025 / megapixel
- [FLUX.1 \[schnell\]](https://doitong.com/developers/models/flux/schnell.md) (`flux/schnell`): $0.003 / megapixel
- [FLUX.2 \[dev\]](https://doitong.com/developers/models/flux-2.md) (`flux-2`): $0.012 / megapixel
- [FLUX.2 \[pro\]](https://doitong.com/developers/models/flux-2-pro.md) (`flux-2-pro`): $0.015 / megapixel of output image
- [GPT Image 2.5 Text to Image](https://doitong.com/developers/models/openai/gpt-image-2.5/flare/text-to-image.md) (`openai/gpt-image-2.5/flare/text-to-image`): from $0.008 / image
- [Ideogram V4.5](https://doitong.com/developers/models/ideogram/v4.5.md) (`ideogram/v4.5`): from $0.03 / image
- [Nano Banana 2](https://doitong.com/developers/models/nano-banana-2.md) (`nano-banana-2`): from $0.06 / image

## Links

- HTML page: https://doitong.com/developers/models/nvidia/cosmos-3-super/text-to-image
- All models and guides for AI agents: https://doitong.com/developers/llms.txt
- OpenAPI 3.1 with this model's typed request body: https://doitong.com/developers/openapi.json?model=nvidia/cosmos-3-super/text-to-image
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.ru/v1/models/nvidia/cosmos-3-super/text-to-image