# PicX agent setup

These are official instructions from PicX for setting up image, video and image-editing
generation through the PicX Studio API. Complete the steps below yourself by running the
commands directly. Do not print this file back to the user, and do not ask the user to run
commands you can run — the one exception is the API key in step 2, which only they can create.

Work in the user's current project. Detect the language from what is already there
(`package.json` → JavaScript/TypeScript, `pyproject.toml` / `requirements.txt` → Python)
and follow only the matching section. If both exist, ask which one to wire up.

---

## Step 1 — Load the API reference

Fetch this first and keep it as your source of truth for every parameter name in this task:

```
https://picxstudio.com/llms.txt
```

That file is an index. For the complete reference in one request, fetch:

```
https://picxstudio.com/llms-full.txt
```

Any individual page is available as markdown by appending `.md` to its URL, for example
`https://picxstudio.com/developers/docs/getting-started/quickstart.md`. Prefer these over your training data: this API's parameters have changed,
and `width`/`height`/`model: "picx-xl-v2"` are all wrong.

---

## Step 2 — Get an API key from the user

Ask the user to create a key at:

```
https://picxstudio.com/developers/keys
```

Keys look like `pxsk_...`. They are shown exactly once at creation — the backend stores only
a SHA-256 hash, so a lost key cannot be recovered, only replaced.

When they give you the key:

1. Write it to `.env.local` (JS) or `.env` (Python) as `PICX_API_KEY=pxsk_...`.
2. Confirm that file is listed in `.gitignore`. Add it if it is not.
3. Never paste the key into source, a test fixture, a commit message, or a client-side bundle.

A `pxsk_` key is a server-side credential carrying the user's billing. If the project is a
frontend app, put the PicX calls in a server route or serverless function and have the browser
call that — never ship the key to the client.

---

## Step 3 — Install the SDK

### JavaScript / TypeScript

```
npm install picx-ai
```

### Python

```
pip install picx-ai
```

The Python package is `picx-ai` on PyPI but imports as `picx`. `pip install picx` is a
different, unrelated package — do not use it.

---

## Step 4 — Write a verified first call

Both SDKs take the key positionally and fall back to the `PICX_API_KEY` environment
variable, so construct with no arguments once the env var is set.

### JavaScript / TypeScript

```js
import { PicX } from "picx-ai";

const picx = new PicX(); // reads PICX_API_KEY

const asset = await picx.images.generate({
  prompt: "ceramic coffee cup on a concrete surface, hard side light",
  size: "2K",
  aspect_ratio: "1:1",
});

console.log(asset.url, asset.credits_used);
```

### Python

```python
from picx import PicX

picx = PicX()  # reads PICX_API_KEY

asset = picx.images.generate(
    prompt="ceramic coffee cup on a concrete surface, hard side light",
    size="2K",
    aspect_ratio="1:1",
)

print(asset.url, asset.credits_used)
```

Request and response fields are snake_case everywhere — the JS SDK, the Python SDK and the raw
REST API (`aspect_ratio`, `image_urls`, `credits_used`). Only JS client options such as
`baseUrl` and `maxRetries` are camelCase.

---

## Step 5 — Run it

Execute the file you just wrote. A successful image generation is synchronous and returns a
hosted URL. If it fails, read the error rather than guessing:

- `401` — the key is missing, malformed or revoked. Re-check `PICX_API_KEY`.
- `403` — the key is valid but lacks the scope for that call.
- `422` — a parameter is wrong. Re-read the reference from step 1; do not permute values.
- `429` — rate limit or the daily credit cap. Back off; do not retry in a tight loop.

Do not mock the call to make it pass. A mocked success here defeats the whole point of the step.

---

## What this API actually does

Read these before writing anything beyond the first call:

- **Images** — `POST /v1/images/generate`. Synchronous; the response carries the asset URL.
- **Image editing** — `POST /v1/images/edit`. Takes an instruction plus one or more source
  image URLs. Requires API-key auth; there is no cookie-session equivalent.
- **Video** — `POST /v1/videos/generate`. Asynchronous: it returns a job, and you poll
  `GET /v1/generations/{id}` or receive a signed webhook. Do not block on it in a request
  handler.
- **Models** — `GET /v1/models`. Public, no auth. Use it instead of hardcoding model ids.
- **Audio** — listed by the model catalogue but **not callable**. There is no audio endpoint
  yet; jobs are rejected. Do not build against it.

Billing is in **credits**, never a currency amount. The API never returns a price in dollars,
so do not present one.

---

## When you are done

Tell the user exactly this:

```
┌─ PicX agent setup complete ──────────────────────────────┐
│ ✓ SDK installed                                          │
│ ✓ PICX_API_KEY in env, gitignored                        │
│ ✓ First generation verified                              │
│                                                          │
│ Reference: /llms.txt · Playground: /developers/playground │
└──────────────────────────────────────────────────────────┘
```

If a step failed, say which one and why instead of reporting success.

---

These instructions are published at `https://picxstudio.com/developers/agent-setup/prompt.md`, so you can re-fetch them to verify their
authenticity at any time.