# Quickstart

> Make your first Raywake API request: choose a model, quote the input, start a generation and poll for results with curl, Python or JavaScript.

Canonical: https://raywake.si/docs/quickstart
Last updated: 2026-10-25

Every generation is two requests and a poll: a **quote** fixes the price of the exact input, a **generation** spends it, and the **job** tells you when the result is ready.

## 1. Set your key

Shell:

```
export RAYWAKE_API_KEY="your key from the API keys page"
```

## 2. Run the full flow

**Quickstart**

cURL:

```bash
# 1. Price the exact input (quotes are valid for up to 10 minutes)
curl -s https://api.raywake.com/v1/quotes \
  -H "Authorization: Bearer $RAYWAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "nano-banana-pro",
  "input": {
    "prompt": "A red ceramic cup on a wooden table, soft morning light",
    "aspect_ratio": "1:1"
  }
}'

# 2. Start the generation with the quote_id from step 1
curl -s https://api.raywake.com/v1/generate \
  -H "Authorization: Bearer $RAYWAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model": "nano-banana-pro", "quote_id": "QUOTE_ID", "input": {"prompt":"A red ceramic cup on a wooden table, soft morning light","aspect_ratio":"1:1"}}'

# 3. Poll until the status is terminal
curl -s https://api.raywake.com/v1/jobs/JOB_ID \
  -H "Authorization: Bearer $RAYWAKE_API_KEY"
```

Python:

```python
import json, os, time, uuid, requests

BASE = "https://api.raywake.com"
HEADERS = {"Authorization": f"Bearer {os.environ['RAYWAKE_API_KEY']}"}
payload = json.loads(r'''{
  "model": "nano-banana-pro",
  "input": {
    "prompt": "A red ceramic cup on a wooden table, soft morning light",
    "aspect_ratio": "1:1"
  }
}''')

# 1. Price the exact input
def read_response(response):
    response.raise_for_status()
    return response.json()

quote = read_response(requests.post(f"{BASE}/v1/quotes", json=payload, headers=HEADERS))
print("Price (USD):", quote["price_usd"])

# 2. Start the generation; keep the same Idempotency-Key when retrying this request
job = read_response(requests.post(
    f"{BASE}/v1/generate",
    json={**payload, "quote_id": quote["quote_id"]},
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
))

# 3. Poll until the result is ready
# Held states (needs_review, submission_unknown, needs_reconciliation) can still change: check them again later.
while job["status"] not in ("succeeded", "failed", "needs_review", "submission_unknown", "needs_reconciliation"):
    time.sleep(2)
    job = read_response(requests.get(f"{BASE}/v1/jobs/{job['job_id']}", headers=HEADERS))

for output in job["outputs"]:
    print(output["type"], output["url"])
```

JavaScript:

```javascript
const BASE = "https://api.raywake.com";
const headers = {
  Authorization: `Bearer ${process.env.RAYWAKE_API_KEY}`,
  "Content-Type": "application/json",
};
const payload = { model: "nano-banana-pro", input: {
  "prompt": "A red ceramic cup on a wooden table, soft morning light",
  "aspect_ratio": "1:1"
} };

async function readResponse(response) {
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  return response.json();
}

// 1. Price the exact input
const quote = await fetch(`${BASE}/v1/quotes`, { method: "POST", headers, body: JSON.stringify(payload) })
  .then(readResponse);

// 2. Start the generation; keep the same Idempotency-Key when retrying this request
let job = await fetch(`${BASE}/v1/generate`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ ...payload, quote_id: quote.quote_id }),
}).then(readResponse);

// 3. Poll until the result is ready
// Held states (needs_review, submission_unknown, needs_reconciliation) can still change: check them again later.
const terminal = ["succeeded", "failed", "needs_review", "submission_unknown", "needs_reconciliation"];
while (!terminal.includes(job.status)) {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  job = await fetch(`${BASE}/v1/jobs/${job.job_id}`, { headers }).then(readResponse);
}
console.log(job.outputs.map((output) => output.url));
```

## 3. Read the result

A finished job looks like this. Output URLs point to our storage and are signed for 7 days; fetch the job again for a fresh link.

Response:

```json
{
  "job_id": "5b0e6c1e-9f5a-4a7e-8f3e-0c6f9d2a41b7",
  "status": "succeeded",
  "model": "nano-banana-pro",
  "prompt": "A red ceramic cup on a wooden table, soft morning light",
  "image_url": "https://…/media/outputs/…/0",
  "outputs": [
    { "type": "image", "url": "https://…/media/outputs/…/0", "mime_type": "image/png", "thumbnail_url": "https://…" }
  ],
  "error": null,
  "quote_id": "9c1d4b7e-2f6a-4e0b-8d3c-5a7f1e2b6c90",
  "reserved_usd": "0.24",
  "charged_usd": "0.24",
  "created_at": "2026-09-25T12:00:00Z",
  "completed_at": "2026-09-25T12:00:14Z"
}
```

Runnable versions of this flow in Python, JavaScript and curl, plus model and recipe examples, are in [raywake-examples on GitHub](https://github.com/oguzhankayan/raywake-examples). Each script requests a free quote unless you pass `--generate`.

[Authentication](https://raywake.si/docs/authentication)

## Related

- [API documentation](https://raywake.si/docs)
