# OKTA Agent Kit: LLM README

Use this file when a coding agent needs to install, inspect, or integrate OKTA Studio quickly.

## Goal

Use OKTA Studio to:

- inspect available models
- check credits
- list past generations
- list, select, upload, and download media-library assets
- create images
- edit images with one or more references
- create videos
- integrate these flows into an app or backend

## Preferred Interface

Use the bundled CLI first.

Windows:

```powershell
.\okta.cmd --json models list --type image
```

macOS / Linux:

```bash
sh ./okta --json models list --type image
```

Fallback:

```bash
node skills/okta-cli/scripts/onyx-cli.mjs --json models list --type image
```

Only use raw HTTP calls when the CLI does not support the needed endpoint yet.

## Required Environment

Set:

```text
OKTA_API_KEY=onyx_sk_...
```

Optional:

```text
OKTA_API_URL=https://okta.studio
```

## Files In This Kit

- `okta.cmd`: Windows wrapper
- `okta`: POSIX wrapper
- `skills/okta-cli/scripts/onyx-cli.mjs`: CLI implementation
- `skills/okta-cli/SKILL.md`: agent-facing usage instructions
- `skills/okta-cli/agents/openai.yaml`: metadata for skill-aware runtimes

## Fast Start

1. Set `OKTA_API_KEY`.
2. Run `config show` or `models list`.
3. Use `--json` for machine-readable output.
4. Use `--output <path>` when you need the generated asset on disk.
5. If a generation returns `status: "processing"`, poll it with `generations status --job-id <id>`.

## Safe Defaults

- Prefer `--json`.
- Prefer the wrapper command over handwritten `curl`.
- Run `config test` before paid operations if environment state is uncertain.
- Use `gpt-image-2` as the default image model unless the user explicitly asks
  for another model.
- Use `node skills/okta-cli/scripts/quote-price.mjs` for code-default customer
  quotes; use `models list` for live default prices.
- Use absolute output paths when another tool or agent will consume the file.
- Do not embed the API key in frontend code.

## Command Cheatsheet

Inspect setup:

```powershell
.\okta.cmd --json meta info
.\okta.cmd --json config show
.\okta.cmd --json config test
```

Read-only API access:

```powershell
.\okta.cmd --json models list --type image
.\okta.cmd --json credits show
.\okta.cmd --json generations list --type video --limit 5
.\okta.cmd --json generations status --job-id <job_id>
.\okta.cmd --json assets list --source upload --limit 10
.\okta.cmd --json assets select --id <asset_id> --output C:\temp\asset.png
.\okta.cmd --json assets upload --file C:\temp\reference.png --name reference.png
```

Create an image:

```powershell
.\okta.cmd --json image create `
  --model gpt-image-2 `
  --prompt "Luxury watch on dark velvet, studio light" `
  --aspect-ratio 16:9 `
  --quality medium `
  --output C:\temp\watch.png
```

Edit an image:

```powershell
.\okta.cmd --json image edit `
  --model gpt-image-2 `
  --prompt "Replace the background with a clean white studio backdrop" `
  --image-url https://example.com/input.jpg `
  --aspect-ratio 1:1 `
  --quality medium `
  --output C:\temp\edited.png
```

Edit with multiple references:

```powershell
.\okta.cmd --json image edit `
  --model gpt-image-2 `
  --prompt "Create a product hero using the product, logo, and lighting reference" `
  --image-urls https://example.com/product.png,https://example.com/logo.png,https://example.com/light.jpg `
  --aspect-ratio 4:5 `
  --quality medium `
  --output C:\temp\hero.png
```

Create a video:

```powershell
.\okta.cmd --json video create `
  --model veo-3.1-fast `
  --prompt "Slow cinematic orbit around the product" `
  --image-url https://example.com/start.png `
  --duration 6 `
  --aspect-ratio 16:9 `
  --output C:\temp\product.mp4
```

If an image or video command returns `status: "processing"`, keep the `job_id`
and run:

```powershell
.\okta.cmd --json generations status --job-id <job_id> --output C:\temp\result.png
```

## Integration Pattern

For backend or server integration:

1. keep `OKTA_API_KEY` in server-side environment variables
2. use the CLI for ops or prototyping
3. move to direct API calls in application code if tighter runtime control is needed
4. keep model IDs configurable
5. log job IDs, model IDs, credit usage, output URLs, and `status_url` when present

## When To Fall Back To Raw API

Fall back only if:

- the CLI does not expose the endpoint
- you need custom HTTP behavior not covered by the CLI
- you are implementing production-side direct API integration in code

Base API path:

```text
https://okta.studio/api/v1
```

Auth header:

```text
Authorization: Bearer onyx_sk_...
```

## Typical Agent Tasks

- "Install the OKTA agent kit and verify credentials."
- "Generate a product image and save it locally."
- "Generate a short product video from an existing start image."
- "Add OKTA image generation to a Next.js API route."
- "Show me available image and video models with current live default prices."

## Expected Agent Behavior

- explain which command is being run
- keep outputs structured when possible
- avoid destructive actions
- do not leak secrets into code, logs, or client bundles
- prefer small reproducible steps over large undocumented changes