# Getting started

> Create an API key and generate a first image with the TypeScript SDK, the REST API, or the CLI.

You need an API key and one request. Pick how you want to work below.

> **Prompt to give a coding agent**
>
> Integrate Mynth media generation into this project. First read the docs: run `npx @mynthio/cli
> docs list` and `npx @mynthio/cli docs get getting-started`. Docs need no account. Before you
> change anything, ask me how to handle credentials: (1) you run `npx @mynthio/cli auth login` and
> `npx @mynthio/cli api-key create my-app`, I approve the login in my browser, and you add the key
> to the right env file; or (2) I add MYNTH_API_KEY myself. Then scan the codebase, tell me where
> media generation would fit, and wait for my go-ahead. Use @mynthio/sdk in TypeScript or JavaScript
> projects. Always pass an explicit model id, never `auto`. Keep the API key on the server.

## Using the SDK

### Get an API key

Log in once with the CLI. It opens your browser to approve the login. Then
create a key for your app:

```bash
npx @mynthio/cli auth login
npx @mynthio/cli api-key create my-app
```

`api-key create` prints a `mak_...` key once. Put it where your app reads
environment variables:

```bash
MYNTH_API_KEY=mak_...
```

You can also create a key in the [dashboard](https://mynth.io/dashboard/keys).

### Install the SDK

**pnpm**

```bash
pnpm add @mynthio/sdk
```

**npm**

```bash
npm install @mynthio/sdk
```

**bun**

```bash
bun add @mynthio/sdk
```

**yarn**

```bash
yarn add @mynthio/sdk
```

### Generate an image

```ts
import Mynth from "@mynthio/sdk";

const mynth = new Mynth(); // reads MYNTH_API_KEY

const task = await mynth.image.generate({
  model: "black-forest-labs/flux.2-pro",
  prompt: "A lighthouse at dusk, film grain",
});

console.log(task.urls[0]);
```

`generate()` creates the task, waits for it, and returns the finished result.
The URL is served for 7 days. [Tasks](https://mynth.io/docs/concepts/tasks.md#file-lifetimes)
covers keeping the file longer.

## Using the REST API

### Get an API key

Log in once with the CLI. It opens your browser to approve the login. Then
create a key and export it:

```bash
npx @mynthio/cli auth login
npx @mynthio/cli api-key create my-app
export MYNTH_API_KEY=mak_...
```

`api-key create` prints the key once. You can also create a key in the
[dashboard](https://mynth.io/dashboard/keys).

### Create a task

```bash
curl https://api.mynth.io/image/generate \
  -H "Authorization: Bearer $MYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "black-forest-labs/flux.2-pro", "prompt": "A lighthouse at dusk, film grain" }'
```

```json
{
  "data": {
    "taskId": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
    "estimatedCost": "0.03",
    "access": { "publicAccessToken": "pat_eyJhbGciOiJIUzI1NiJ9..." }
  }
}
```

Generation is asynchronous. The response is a task id, not an image.

### Poll for the result

Poll the status until it leaves `pending`, then read the result:

```bash
curl https://api.mynth.io/tasks/tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP/status \
  -H "Authorization: Bearer $MYNTH_API_KEY"

curl https://api.mynth.io/tasks/tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP/result \
  -H "Authorization: Bearer $MYNTH_API_KEY"
```

```json
{
  "data": {
    "id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
    "type": "image.generate",
    "status": "completed",
    "result": {
      "model": "black-forest-labs/flux.2-pro",
      "images": [
        {
          "status": "success",
          "id": "img_V1StGXR8Z5jdHi6BmyT0sC1pQ2rN4wLk",
          "url": "https://cdn.mynth.io/images/img_V1StGXR8Z5jdHi6BmyT0sC1pQ2rN4wLk.webp",
          "mynth_url": "https://cdn.mynth.io/images/img_V1StGXR8Z5jdHi6BmyT0sC1pQ2rN4wLk.webp",
          "size": "1536x1024",
          "format": "webp"
        }
      ]
    }
  }
}
```

Check `status` on each image, not only on the task. To skip polling, register
a [webhook](https://mynth.io/docs/concepts/webhooks.md). [Poll for results](https://mynth.io/docs/guides/poll-for-results.md)
has a polling loop to copy.

## Using the CLI

### Log in

```bash
npx @mynthio/cli auth login
```

Approve the one-time code in the browser. The CLI creates an API key and
stores it on this machine, so later commands need no `MYNTH_API_KEY`.

### Generate an image

```bash
npx @mynthio/cli image generate \
  -m black-forest-labs/flux.2-pro \
  -p "A lighthouse at dusk, film grain"
```

The CLI waits for the task and prints the image URL. Add `-o ./images` to save
the file, or `--json` for output a script or agent can parse.

```bash
npx @mynthio/cli models list    # model ids you can pass to -m
npx @mynthio/cli task list      # your recent tasks
npx @mynthio/cli balance        # balance, reserved, available
```

`npm install -g @mynthio/cli` installs the `mynth` binary, so you can drop the
`npx @mynthio/cli` prefix.

## Next steps

- [Tasks](https://mynth.io/docs/concepts/tasks.md): statuses, partial failure, and file lifetimes.
- [The model field](https://mynth.io/docs/models.md): what `model` accepts and where to find ids.
- [Webhooks](https://mynth.io/docs/concepts/webhooks.md): get called when a task settles.