# Cosmos API

> Provider: **NVIDIA**
> Source: https://www.pixazo.ai/models/cosmos

Cosmos 3 Super API delivers a unified, high-performance integration layer designed to streamline complex data workflows and accelerate digital transformation across enterprise ecosystems. This robust solution offers developers seamless connectivity, exceptional uptime, and low-latency processing to handle demanding workloads without compromising on speed or reliability. With its intuitive architecture and advanced security protocols, the platform simplifies API management, automates routine tasks, and scales effortlessly to meet growing business demands. By eliminating operational bottlenecks and ensuring data consistency across various internal endpoints, it empowers organizations to optimize their software architecture and unlock maximum technical efficiency.

## Cosmos 3 Super

### Text to Image

## Base URL

```
https://gateway.pixazo.ai/cosmos-3-super-text-to-image/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Cosmos 3 Super Text to Image generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/cosmos-3-super-text-to-image/v1/cosmos-3-super-text-to-image-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A futuristic mountain observatory under a star-filled sky, cinematic lighting, photorealistic",
  "negative_prompt": "",
  "image_size": "square_hd",
  "num_inference_steps": 28,
  "guidance_scale": 4,
  "num_images": 1,
  "output_format": "jpeg",
  "enable_prompt_expansion": false,
  "enable_safety_checker": true,
  "sync_mode": false
}
```

```
import requests

url = "https://gateway.pixazo.ai/cosmos-3-super-text-to-image/v1/cosmos-3-super-text-to-image-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A futuristic mountain observatory under a star-filled sky, cinematic lighting, photorealistic",
    "negative_prompt": "",
    "image_size": "square_hd",
    "num_inference_steps": 28,
    "guidance_scale": 4,
    "num_images": 1,
    "output_format": "jpeg",
    "enable_prompt_expansion": false,
    "enable_safety_checker": true,
    "sync_mode": false
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = "https://gateway.pixazo.ai/cosmos-3-super-text-to-image/v1/cosmos-3-super-text-to-image-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "prompt": "A futuristic mountain observatory under a star-filled sky, cinematic lighting, photorealistic",
  "negative_prompt": "",
  "image_size": "square_hd",
  "num_inference_steps": 28,
  "guidance_scale": 4,
  "num_images": 1,
  "output_format": "jpeg",
  "enable_prompt_expansion": false,
  "enable_safety_checker": true,
  "sync_mode": false
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/cosmos-3-super-text-to-image/v1/cosmos-3-super-text-to-image-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A futuristic mountain observatory under a star-filled sky, cinematic lighting, photorealistic",
    "negative_prompt": "",
    "image_size": "square_hd",
    "num_inference_steps": 28,
    "guidance_scale": 4,
    "num_images": 1,
    "output_format": "jpeg",
    "enable_prompt_expansion": false,
    "enable_safety_checker": true,
    "sync_mode": false
  }'
```

## Output

```
{
  "request_id": "cosmos-3-super-text-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/cosmos-3-super-text-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=cosmos-3-super-text-to-image&operation=cosmos-3-super-text-to-image-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Cosmos 3 Super Text to Image generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

1–4096 characters

Text prompt for image generation (1-4096 characters).

negative\_prompt

No

string

""

≤ 1024 characters

Content to steer away from during generation (max 1024 characters).

enable\_prompt\_expansion

No

boolean

false

—

Expand the prompt via OpenRouter before generation. Enabled prompts are billed at +$0.02 per request.

enable\_agentic\_generation

No

boolean

false

—

Enable iterative generation and comparison of multiple candidate images. Each candidate is billed separately.

agentic\_max\_iterations

No

integer

2

1–3

Maximum refinement rounds (1-3). Only applies if enable\_agentic\_generation is true.

agentic\_samples\_per\_iteration

No

integer

2

1–3

Number of candidate images generated per iteration (1-3). Only applies if enable\_agentic\_generation is true.

agentic\_early\_stop

No

boolean

true

—

Stop refinement early if a candidate is deemed a strong match. Only applies if enable\_agentic\_generation is true.

image\_size

No

string or object

"square\_hd"

"square\_hd", "square", "portrait\_4\_3", "portrait\_16\_9", "landscape\_4\_3", "landscape\_16\_9", or {width: integer, height: integer}

Preset aspect ratios: square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9. Alternatively, provide a custom object: {"width": integer, "height": integer}.

num\_inference\_steps

No

integer

28

1–50

Number of denoising steps (1-50). Higher values improve quality but increase processing time.

guidance\_scale

No

float

4

0–20

Classifier-free guidance scale (0-20). Higher values increase prompt adherence at the cost of diversity.

num\_images

No

integer

1

1–4

Number of images to generate (1-4). Each image is billed at $0.04.

output\_format

No

string

"jpeg"

"jpeg", "png"

Output image format. Allowed: jpeg, png.

enable\_safety\_checker

No

boolean

true

—

Enable content moderation to filter NSFW or harmful outputs.

seed

No

integer

—

—

Random seed for reproducible results. If omitted, a random seed is used.

sync\_mode

No

boolean

false

—

If true, returns the generated image(s) as base64-encoded data URIs inline in the response. Otherwise, returns a request\_id for async polling.

## Example Request

```
{
  "prompt": "A futuristic mountain observatory under a star-filled sky, cinematic lighting, photorealistic",
  "negative_prompt": "",
  "image_size": "square_hd",
  "num_inference_steps": 28,
  "guidance_scale": 4,
  "num_images": 1,
  "output_format": "jpeg",
  "enable_prompt_expansion": false,
  "enable_safety_checker": true,
  "sync_mode": false
}
```

## Response

```
{
  "request_id": "cosmos-3-super-text-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/cosmos-3-super-text-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'cosmos-3-super-text-to-image' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "cosmos-3-super-text-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "cosmos-3-super-text-to-image",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/cosmos-3-super-text-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "cosmos-3-super-text-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "cosmos-3-super-text-to-image",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/cosmos-3-super-text-to-image_019dxxxx/output.jpg"],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Image to Video

## Base URL

```
https://gateway.pixazo.ai/cosmos-3-super-image-to-video/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Cosmos 3 Super Image to Video generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/cosmos-3-super-image-to-video/v1/cosmos-3-super-image-to-video-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "Cinematic slow camera push-in; the subject animates naturally",
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
  "num_frames": 189,
  "frames_per_second": 24,
  "num_inference_steps": 28,
  "guidance_scale": 6,
  "enable_prompt_expansion": true,
  "enable_safety_checker": true,
  "sync_mode": false
}
```

```
import requests

url = "https://gateway.pixazo.ai/cosmos-3-super-image-to-video/v1/cosmos-3-super-image-to-video-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "Cinematic slow camera push-in; the subject animates naturally",
    "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
    "num_frames": 189,
    "frames_per_second": 24,
    "num_inference_steps": 28,
    "guidance_scale": 6,
    "enable_prompt_expansion": true,
    "enable_safety_checker": true,
    "sync_mode": false
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = "https://gateway.pixazo.ai/cosmos-3-super-image-to-video/v1/cosmos-3-super-image-to-video-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "prompt": "Cinematic slow camera push-in; the subject animates naturally",
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
  "num_frames": 189,
  "frames_per_second": 24,
  "num_inference_steps": 28,
  "guidance_scale": 6,
  "enable_prompt_expansion": true,
  "enable_safety_checker": true,
  "sync_mode": false
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/cosmos-3-super-image-to-video/v1/cosmos-3-super-image-to-video-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "Cinematic slow camera push-in; the subject animates naturally",
    "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
    "num_frames": 189,
    "frames_per_second": 24,
    "num_inference_steps": 28,
    "guidance_scale": 6,
    "enable_prompt_expansion": true,
    "enable_safety_checker": true,
    "sync_mode": false
  }'
```

## Output

```
{
  "request_id": "cosmos-3-super-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/cosmos-3-super-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=cosmos-3-super-image-to-video&operation=cosmos-3-super-image-to-video-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Cosmos 3 Super Image to Video generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

non-empty; ≤ 4096 chars

Text describing motion and scene (max 4096 characters). Must describe dynamic elements such as camera movement, object motion, or environmental changes.

image\_url

Yes

string

—

—

URL of the conditioning first-frame image. Must be publicly accessible.

negative\_prompt

No

string

"blurry, low quality, distorted, unnatural motion, flickering, stuttering, deformed limbs, extra limbs, bad anatomy"

≤ 2048 chars

Content to steer away from during generation (max 2048 characters).

enable\_prompt\_expansion

No

boolean

true

—

Rewrite prompt via Cosmos3-Nano Reasoner to enhance motion description and scene context.

enable\_agentic\_generation

No

boolean

false

—

Enable iterative agentic refinement loop for improved motion quality.

agentic\_max\_iterations

No

integer

2

1, 2, 3

Maximum number of agentic refinement stages.

agentic\_samples\_per\_iteration

No

integer

2

1, 2, 3

Number of candidate videos generated per agentic iteration.

agentic\_early\_stop

No

boolean

true

—

Stop agentic loop early when the critic score exceeds the threshold.

image\_size

No

string or object

{"width":832,"height":480}

square\_hd, square, portrait\_4\_3, portrait\_16\_9, landscape\_4\_3, landscape\_16\_9

Preset aspect ratio or custom dimensions. Custom object must include width and height as integers.

num\_frames

No

integer

189

5–189

Number of frames in output video.

frames\_per\_second

No

integer

24

4–60

Output frame rate.

num\_inference\_steps

No

integer

28

1–50

Number of denoising steps during generation.

guidance\_scale

No

float

6

0–20

Classifier-free guidance scale for prompt adherence.

enable\_safety\_checker

No

boolean

true

—

Enable content moderation for input prompt and image to block prohibited content.

seed

No

integer

—

—

Random seed for reproducible results. If omitted, a random seed is used.

sync\_mode

No

boolean

false

—

If true, returns the video as a base64-encoded data URI inline in the response. Otherwise, returns a media URL.

## Example Request

```
{
  "prompt": "Cinematic slow camera push-in; the subject animates naturally",
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
  "num_frames": 189,
  "frames_per_second": 24,
  "num_inference_steps": 28,
  "guidance_scale": 6,
  "enable_prompt_expansion": true,
  "enable_safety_checker": true,
  "sync_mode": false
}
```

## Response

```
{
  "request_id": "cosmos-3-super-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/cosmos-3-super-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'cosmos-3-super-image-to-video' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "cosmos-3-super-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "cosmos-3-super-image-to-video",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/cosmos-3-super-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "cosmos-3-super-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "cosmos-3-super-image-to-video",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/cosmos-3-super-image-to-video_019dxxxx/output.mp4"],
    "media_type": "video/mp4"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.