# Quickstart

> Make your first render in four steps. Copy each snippet, run it, and move on.

Source: https://developers.mnml.ai/docs/quickstart

> [!TIP]
> **What you need:** an mnml.ai account, $10 or more to top up your API wallet (your first top-up adds $5 free), and a terminal with `curl`, or any HTTP client.

### Step 1: Top up your API wallet

[Sign up](https://developers.mnml.ai/signup), or sign in with your mnml.ai account, then add funds on the console’s [Billing](https://developers.mnml.ai/console/billing) page. Your Studio plan and balance do not pay for API calls.

### Step 2: Create an API key

Open [API keys](https://developers.mnml.ai/console/keys) in the console, create a key and copy it. It is shown only once, so save it as an environment variable now.

**Terminal**

```bash
export MNML_API_KEY=mk_live_…
```

### Step 3: Send a render

Send an image and a prompt. The answer comes straight away with a job `id`, and charges $0.2475 for v4.6.

**curl**

```bash
curl -X POST https://api.mnml.ai/v2/renders \
  -H "Authorization: Bearer $MNML_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "engine": "v4.6-ultra",
    "mode": "exterior",
    "image": "https://example.com/massing.png",
    "prompt": "Timber facade, late afternoon, olive trees"
  }'
```

**TypeScript**

```ts
const res = await fetch("https://api.mnml.ai/v2/renders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MNML_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "engine": "v4.6-ultra",
    "mode": "exterior",
    "image": "https://example.com/massing.png",
    "prompt": "Timber facade, late afternoon, olive trees"
  }),
});

const data = await res.json();
```

**Python**

```python
import os, requests

res = requests.post(
    "https://api.mnml.ai/v2/renders",
    headers={"Authorization": f"Bearer {os.environ['MNML_API_KEY']}"},
    json={
      "engine": "v4.6-ultra",
      "mode": "exterior",
      "image": "https://example.com/massing.png",
      "prompt": "Timber facade, late afternoon, olive trees"
    },
)

data = res.json()
```

**Answer · 202**

```json
{
  "success": true,
  "data": {
    "id": "10482",
    "status": "queued",
    "charged_usd": 0.2475,
    "credits_charged": 25,
    "replayed": false,
    "notes": [],
    "ids": [
      "10482"
    ]
  }
}
```

### Step 4: Get the result

Ask for the job every few seconds. When its `status` is `succeeded`, `outputs[0].url` is your render: download it, as the link expires after an hour or two.

**curl**

```bash
curl https://api.mnml.ai/v2/jobs/10482 \
  -H "Authorization: Bearer $MNML_API_KEY"
```

**TypeScript**

```ts
const res = await fetch("https://api.mnml.ai/v2/jobs/10482", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MNML_API_KEY}`,
  },
});

const data = await res.json();
```

**Python**

```python
import os, requests

res = requests.get(
    "https://api.mnml.ai/v2/jobs/10482",
    headers={"Authorization": f"Bearer {os.environ['MNML_API_KEY']}"},
)

data = res.json()
```

> [!NOTE]
> A job that fails is refunded. Read [Jobs and polling](https://developers.mnml.ai/docs/jobs) for every status.

## Or use an SDK

The official SDKs make the same calls, wait for the job for you, retry safely and verify webhooks. Each reads your key from `MNML_API_KEY`.

| Language | Install | Source |
| --- | --- | --- |
| TypeScript | `npm install @mnml-ai/sdk` | [github.com/mnml-ai/mnml-sdk-typescript](https://github.com/mnml-ai/mnml-sdk-typescript) |
| Python | `pip install mnml-ai` | [github.com/mnml-ai/mnml-sdk-python](https://github.com/mnml-ai/mnml-sdk-python) |
| PHP | `composer require mnml-ai/sdk` | [github.com/mnml-ai/mnml-sdk-php](https://github.com/mnml-ai/mnml-sdk-php) |
| Go | `go get github.com/mnml-ai/mnml-sdk-go` | [github.com/mnml-ai/mnml-sdk-go](https://github.com/mnml-ai/mnml-sdk-go) |
| C# and .NET | `dotnet add package Mnml.Sdk` | [github.com/mnml-ai/mnml-sdk-dotnet](https://github.com/mnml-ai/mnml-sdk-dotnet) |

**TypeScript**

```ts
import { Mnml } from '@mnml-ai/sdk';

const mnml = new Mnml(); // reads MNML_API_KEY

const [job] = await mnml.renders.createAndWait({
  mode: 'exterior',
  image: 'https://example.com/massing.png', // or the file's bytes: await readFile('massing.png')
  prompt: 'Timber facade, late afternoon light, olive trees',
});
console.log(job?.status, job?.outputs[0]?.url);
```

**Python**

```python
from pathlib import Path

from mnml_ai import Mnml

mnml = Mnml()  # reads MNML_API_KEY

job = mnml.renders.create_and_wait(
    mode="exterior",
    image=Path("massing.png"),  # or a link: "https://example.com/massing.png"
    prompt="Timber facade, late afternoon light, olive trees",
)[0]
print(job["status"], job["outputs"][0]["url"] if job["outputs"] else None)
```

**PHP**

```php
use Mnml\Client;
use Mnml\Image;
use Mnml\Mode;

$mnml = new Client(); // reads MNML_API_KEY

$jobs = $mnml->renders->createAndWait([
    'mode' => Mode::EXTERIOR,
    'image' => Image::fromFile('massing.png'), // or 'https://example.com/massing.png'
    'prompt' => 'Timber facade, late afternoon light, olive trees',
]);
echo $jobs[0]->status, ' ', $jobs[0]->outputs[0]->url;
```

**Go**

```go
package main

import (
	"context"
	"fmt"
	"log"

	mnml "github.com/mnml-ai/mnml-sdk-go"
)

func main() {
	client, err := mnml.NewClient() // reads MNML_API_KEY
	if err != nil {
		log.Fatal(err)
	}
	img, err := mnml.ImageFromFile("massing.png") // or mnml.Image("https://…")
	if err != nil {
		log.Fatal(err)
	}
	jobs, err := client.Renders.CreateAndWait(context.Background(), &mnml.RenderRequest{
		Mode:   mnml.ModeExterior,
		Image:  img,
		Prompt: "Timber facade, late afternoon light, olive trees",
	}, nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(jobs[0].Status, jobs[0].Outputs[0].URL)
}
```

**C#**

```csharp
using Mnml;

using var mnml = new MnmlClient(); // reads MNML_API_KEY

var jobs = await mnml.Renders.CreateAndWaitAsync(new RenderRequest
{
    Mode = Modes.Exterior,
    Image = ImageInput.FromFile("massing.png"), // or a public https:// link
    Prompt = "Timber facade, late afternoon light, olive trees",
});
Console.WriteLine($"{jobs[0].Status} {jobs[0].Outputs[0].Url}");
```

More recipes for each language are on the [SDKs page](https://developers.mnml.ai/sdks).

## Next steps

- [Webhooks](https://developers.mnml.ai/docs/webhooks): Hear when a job finishes instead of polling.
- [Retry safely](https://developers.mnml.ai/docs/idempotency): Idempotency keys stop a retry from charging twice.
- [Every render option](https://developers.mnml.ai/docs/renders): Modes, references, settings and variations.