# AgentHook — full agent reference

> Everything an agent needs to generate video, images, and captions via AgentHook. Generated from the live API contract.

Base URL: https://getagenthook.com/api/v1
Auth: `Authorization: Bearer <api key>` on every request. Keys: https://getagenthook.com/keys (signup grants 30 trial credits).

## Lifecycle

1. `POST https://getagenthook.com/api/v1/tools/<tool>/run` with JSON arguments -> `202 {"run_id", "credits_charged"}`. Credits are debited atomically up front.
2. Poll `GET https://getagenthook.com/api/v1/runs/<run_id>` every ~5s. Non-terminal statuses: `queued`, `processing`.
3. `completed` -> `output` holds permanent media URLs (https://cdn.getagenthook.com/...). `failed` -> `error` explains why and the credits were already refunded.

Rate limits: 10 run-creations/min and 60 reads/min per key -> 429 with Retry-After. Repeated content-moderation rejections suspend the account (403).

## Tools

### make_video

Generate a video (talking-head parity via Seedance native audio) from a prompt and optional reference images.

- `prompt` (string, required, max length 4000)
- `reference_images` (array, max 14)
- `owns_references` (boolean) — Required true when reference_images are attached (likeness consent).
- `model` (string, default: "seedance-2", one of: seedance-2 | kling-3)
- `quality` (string, default: "standard", one of: standard | pro)
- `duration` (number, default: 5)
- `aspect_ratio` (string, default: "9:16", one of: 16:9 | 9:16 | 1:1 | 4:3 | 3:4 | 21:9)
- `audio` (boolean, default: true)
- `captions` (boolean, default: false)
- `caption_style` (string, default: "tiktok", one of: movie | tiktok)
- `enhance_prompt` (boolean, default: false)

```bash
curl -X POST https://getagenthook.com/api/v1/tools/make_video/run \
  -H "Authorization: Bearer $AGENTHOOK_API_KEY" -H "Content-Type: application/json" \
  -d '<json arguments>'
# -> 202 { "run_id": "...", "credits_charged": n }
```

### make_image

Generate or edit an image. With reference_images routes to Nano Banana 2 (RunPod); without, to GPT Image 2 (PiAPI).

- `prompt` (string, required)
- `reference_images` (array, max 14)
- `owns_references` (boolean) — Required true when reference_images are attached (likeness consent).
- `model` (string, default: "auto", one of: auto | nano-banana-2 | gpt-image-2)
- `aspect_ratio` (string, default: "9:16", one of: 1:1 | 16:9 | 9:16 | 4:3 | 3:4 | 3:2 | 2:3 | 21:9)
- `resolution` (string, default: "1k", one of: 1k | 2k | 4k)
- `count` (number, default: 1, max 4)
- `enhance_prompt` (boolean, default: false)

```bash
curl -X POST https://getagenthook.com/api/v1/tools/make_image/run \
  -H "Authorization: Bearer $AGENTHOOK_API_KEY" -H "Content-Type: application/json" \
  -d '<json arguments>'
# -> 202 { "run_id": "...", "credits_charged": n }
```

### caption_video

Burn styled subtitles into an existing video.

- `video_url` (string, required)
- `style` (string, default: "movie", one of: movie | tiktok)
- `language` (string, default: "auto")

```bash
curl -X POST https://getagenthook.com/api/v1/tools/caption_video/run \
  -H "Authorization: Bearer $AGENTHOOK_API_KEY" -H "Content-Type: application/json" \
  -d '<json arguments>'
# -> 202 { "run_id": "...", "credits_charged": n }
```

## Other endpoints

- `GET https://getagenthook.com/api/v1/generations?tool=&status=&q=&cursor=` — your history; `q` is full-text search over prompts and transcripts ("that beach video" works).
- `GET https://getagenthook.com/api/v1/me` — credit balance. `GET https://getagenthook.com/api/v1/credits/history` — the ledger.
- `GET https://getagenthook.com/api/v1/tools` — these schemas as JSON.

## Pricing

1 credit = $0.01 list price. Video = provider list x 1.25. Images = list x 2. Captions flat 15 credits per video. Prompt rewrite +3 credits. Failed generations always refund in full, instantly.

## Consent (required reading for reference images)

Any run with `reference_images` MUST set `owns_references: true`, attesting the caller owns or has rights to the likenesses. The attestation is stored with the run (flag + timestamp + key id). Deepfakes and impersonation are prohibited; moderation strikes suspend accounts.