🔌 API Reference

REST API for programmatic playable ad generation.

Base URL: https://api.opengame.dev/v1

Authentication

All requests require an API key in the Authorization header:


Authorization: Bearer og_sk_live_xxxxxxxxxxxxxx

Get your API key from the dashboard (coming soon).

`POST /v1/generate`

Generate a playable ad from a prompt.

Request Body


{
  "prompt": "A coin rush game with Vietnamese theme, green bamboo background",
  "genre": "auto",
  "locale": "vi",
  "art_style": "cartoon",
  "brand_name": "GameApp",
  "cta_url": "https://apps.apple.com/app/123456",
  "variants": {
    "genres": ["arcade-catch", "tycoon"],
    "locales": ["vi", "en", "th", "id"],
    "count": 3
  }
}

Parameters

Field	Type	Default	Description
`prompt`	string	required	Natural language description of the ad
`genre`	string	`"auto"`	Genre key or `"auto"` for AI routing
`locale`	string	`"en"`	Target locale (`vi`, `en`, `th`, `id`)
`art_style`	string	`"cartoon"`	Visual style (`cartoon`, `realistic`, `pixel`, `cyberpunk`)
`brand_name`	string	null	Brand name to display in HUD
`cta_url`	string	null	App Store / Play Store URL
`variants`	object	null	Variant explosion configuration

Variants Object


{
  "genres": ["arcade-catch", "tycoon", "decision-fomo"],
  "locales": ["vi", "en"],
  "count": 6
}

Produces genres × locales = 6 variants (max 12 per request).

Response (201)


{
  "id": "og_cre_abc123def456",
  "status": "completed",
  "created_at": "2026-04-28T12:00:00Z",
  "prompt": "A coin rush game with Vietnamese theme",
  "variants": [
    {
      "slug": "arcade-catch-vi-v1",
      "genre": "arcade-catch",
      "locale": "vi",
      "size_bytes": 185344,
      "preview_url": "https://preview.opengame.dev/creatives/arcade-catch-vi-v1/playable.html",
      "networks": {
        "applovin": {"url": "https://cdn.opengame.dev/creatives/abc123/applovin.html", "format": "html"},
        "mintegral": {"url": "https://cdn.opengame.dev/creatives/abc123/mintegral.html", "format": "html"},
        "unity": {"url": "https://cdn.opengame.dev/creatives/abc123/unity.html", "format": "html"},
        "ironsource": {"url": "https://cdn.opengame.dev/creatives/abc123/ironsrc.html", "format": "html"},
        "vungle": {"url": "https://cdn.opengame.dev/creatives/abc123/vungle.zip", "format": "zip"},
        "meta": {"url": "https://cdn.opengame.dev/creatives/abc123/meta.zip", "format": "zip"},
        "google": {"url": "https://cdn.opengame.dev/creatives/abc123/google.zip", "format": "zip"},
        "tiktok": {"url": "https://cdn.opengame.dev/creatives/abc123/tiktok.zip", "format": "zip"}
      },
      "validation": {
        "mraid_lint": "pass",
        "bundle_size": "185KB",
        "tiktok_lint": "pass",
        "health_check": "all_healthy"
      }
    }
  ],
  "cost_usd": 9.00
}

Response (202 — async)


{
  "id": "og_cre_abc123def456",
  "status": "processing",
  "estimated_seconds": 300,
  "check_url": "https://api.opengame.dev/v1/generations/og_cre_abc123def456"
}

`GET /v1/generations/:id`

Check generation status and get results.


{
  "id": "og_cre_abc123def456",
  "status": "completed",
  "progress": 1.0,
  "variants": [...],
  "cost_usd": 9.00
}

`GET /v1/genres`

List all available genres and hybrid families.


{
  "genres": [
    {"key": "arcade-catch", "name": "Arcade Catch", "description": "Drag/tap collector", "tier": "free"},
    {"key": "decision-fomo", "name": "Decision FOMO", "description": "Choices under pressure", "tier": "pro"},
    {"key": "tycoon", "name": "Economy Tycoon", "description": "Build, harvest, upgrade", "tier": "pro"},
    {"key": "match-3", "name": "Match-3", "description": "Swap and match", "tier": "pro"},
    {"key": "runner", "name": "Runner", "description": "Auto-forward dodging", "tier": "pro"}
  ],
  "hybrids": [
    {"key": "hybrid-garden-match", "name": "Garden Match", "description": "Tycoon × Match-3", "tier": "enterprise"},
    {"key": "hybrid-coin-rain", "name": "Coin Rain Tycoon", "description": "Arcade × Tycoon", "tier": "enterprise"},
    {"key": "hybrid-merge-run", "name": "Lane Merge Run", "description": "Merge × Runner", "tier": "enterprise"},
    {"key": "hybrid-idle-workshop", "name": "Idle Workshop", "description": "Screw Puzzle × Idle Clicker", "tier": "enterprise"},
    {"key": "hybrid-crisis-empire", "name": "Crisis Empire", "description": "Decision FOMO × Idle Clicker", "tier": "enterprise"}
  ]
}

`POST /v1/validate`

Validate an existing playable ad HTML against MRAID 3.0 + network specs.


{
  "html_content": "<!doctype html>...",
  "targets": ["mraid", "tiktok"]
}

`POST /v1/package`

Package an existing playable.html into all network deliverables.


{
  "html_content": "<!doctype html>...",
  "targets": ["applovin", "mintegral", "unity", "ironsource", "vungle", "meta", "google", "tiktok"]
}

Rate Limits

Tier	RPM	Daily Cap
Free	1 RPM	5/day
Pro	10 RPM	50/day
Enterprise	100 RPM	Custom

Errors


{
  "error": {
    "code": "invalid_prompt",
    "message": "Prompt must be between 10 and 500 characters",
    "details": null
  }
}

Code	HTTP	Meaning
`invalid_prompt`	400	Prompt validation failed
`invalid_genre`	400	Genre key not found
`rate_limit_exceeded`	429	Too many requests
`generation_failed`	500	AI generation error
`insufficient_credits`	402	Out of credits
`unauthorized`	401	Invalid API key