# Hypergen Agent Skill

Hypergen turns a plain product photo into authentic UGC-style content: reusable
AI creators wearing, holding, or using your product as Shopify-ready stills and
vertical TikTok / Instagram Reels / YouTube Shorts video.

This file is the agent skill spec for Codex, OpenClaw, Hermes, Claude, and any
HTTP-capable runtime. Agents should read this file, ask the user for a product
image URL or upload, then call the REST API and poll jobs until complete.

## 1. Credentials

Create an account and API key on the Developers page:

https://hypergen.hypercho.com/app/developers

Set these environment variables in the agent runtime:

```bash
export HYPERGEN_API_KEY="sk_live_..."
export HYPERGEN_API_BASE="https://api.hypercho.com"
```

All requests authenticate with:

```http
Authorization: Bearer $HYPERGEN_API_KEY
Content-Type: application/json
```

## 2. Concepts

- `modelId` is a reusable creator identity. Create it once and reuse it across
  a Shopify catalog so the store has consistent UGC.
- `job` is an async generation with `status` of `queued`, `processing`,
  `completed`, or `failed`.
- `outputUrls` contains generated still images. `videoUrl` contains generated
  video.
- Credits are spent when jobs run. Check `/credits` before large batches.

## 3. Base path

```text
{HYPERGEN_API_BASE}/skill/hypergen
```

## 4. Endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/catalog` | List model engines and provider status |
| GET | `/credits` | Current credit balance |
| GET | `/models` | List reusable creators |
| POST | `/models` | Generate a creator from `{ "random": true }` or `{ "prompt": "..." }` |
| POST | `/models/upload` | Register a reusable creator from image URLs |
| POST | `/generate` | Generate Shopify product-on-creator stills |
| POST | `/video` | Generate 9:16 short-form video from an image |
| GET | `/jobs` | List jobs |
| GET | `/jobs/:id` | Poll one job |

## 5. Request shapes

Create a creator:

```json
{
  "name": "Cozy creator",
  "prompt": "24 year old quiet-luxe UGC creator in a sunlit loft, relaxed natural expression, reusable identity reference",
  "random": false
}
```

Upload an existing creator reference:

```json
{
  "name": "Store creator",
  "images": ["https://example.com/model-reference.jpg"]
}
```

Generate Shopify stills:

```json
{
  "modelId": "<MODEL_ID>",
  "productImage": "https://example.com/product.png",
  "scene": "holding the product near a sunny kitchen counter, soft daylight, clean ecommerce detail",
  "count": 2,
  "aspectRatio": "4:5"
}
```

Generate vertical video:

```json
{
  "image": "<OUTPUT_IMAGE_URL>",
  "prompt": "hook-first unboxing, product visible in the first second, natural UGC pacing, room for captions",
  "durationSeconds": 5,
  "resolution": "720p"
}
```

## 6. End-to-end curl flow

```bash
# 1. Create a reusable creator.
CREATE_RESPONSE=$(curl -s -X POST "$HYPERGEN_API_BASE/skill/hypergen/models" \
  -H "Authorization: Bearer $HYPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cozy creator","prompt":"24 year old quiet-luxe UGC creator in a sunlit loft, relaxed natural expression, reusable identity reference"}')

MODEL_ID=$(echo "$CREATE_RESPONSE" | jq -r '.data.modelId // .modelId')
JOB_ID=$(echo "$CREATE_RESPONSE" | jq -r '.data._id // ._id')

# 2. If creator creation returned a job, poll it until completed.
curl -s "$HYPERGEN_API_BASE/skill/hypergen/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HYPERGEN_API_KEY"

# 3. Generate product-on-creator Shopify images.
PRODUCT_JOB=$(curl -s -X POST "$HYPERGEN_API_BASE/skill/hypergen/generate" \
  -H "Authorization: Bearer $HYPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"modelId\":\"$MODEL_ID\",\"productImage\":\"https://your-store/product.jpg\",\"scene\":\"holding it in bright window light, conversion-ready Shopify detail\",\"count\":2}" \
  | jq -r '.data._id // ._id')

# 4. Poll until completed, then read outputUrls.
curl -s "$HYPERGEN_API_BASE/skill/hypergen/jobs/$PRODUCT_JOB" \
  -H "Authorization: Bearer $HYPERGEN_API_KEY"

# 5. Turn one output image into a vertical short.
curl -s -X POST "$HYPERGEN_API_BASE/skill/hypergen/video" \
  -H "Authorization: Bearer $HYPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"<OUTPUT_IMAGE_URL>","prompt":"hook-first unboxing, product visible in the first second, natural UGC pacing","durationSeconds":5,"resolution":"720p"}'
```

## 7. Agent rules

- Prefer one reusable `modelId` per brand, customer segment, or campaign.
- Do not create a new model for every product unless the user asks for that.
- Always poll `/jobs/:id` until `completed` or `failed`.
- If a job fails with `INSUFFICIENT_CREDITS`, stop and ask the user to add
  credits instead of retrying in a loop.
- Store `modelId`, `outputUrls`, `videoUrl`, prompt, and product SKU together.
- For Shopify, generate 4:5 or square stills; for TikTok/Reels/Shorts, generate
  9:16 video prompts with the product visible in the first second.

## 8. Prompt recipes

Shopify product-on-creator still:

```text
Shopify product-on-creator still: a reusable UGC creator in a clean realistic setting, three-quarter angle with the product clearly in focus, soft daylight, true-to-life color, believable fit and scale, uncluttered background, conversion-ready product detail.
```

Studio packshot:

```text
Shopify product image: premium studio packshot on a clean seamless background with soft contact shadow, crisp material detail, true-to-life color, ecommerce catalog lighting, no text overlay, no watermark.
```

Reels / Shorts video:

```text
Vertical 9:16 short-form video: hook-first unboxing, product visible within the first second, natural UGC movement, three clear benefit beats, room for subtitles, optimized for TikTok, Instagram Reels, and YouTube Shorts.
```

## 9. Codex / OpenClaw / Hermes / Claude quickstart prompt

```text
Connect to Hypergen using this skill spec: https://hypergen.hypercho.com/skills.md.
Use HYPERGEN_API_KEY and HYPERGEN_API_BASE from my environment. Create or reuse a modelId, generate Shopify-ready product-on-creator images from my product photo, then generate one 9:16 short-form video. Poll every job until completed and return the final outputUrls, videoUrl, prompts, and modelId.
```