API Reference

Cortex Asset API — REST endpoints for searching, previewing, downloading, and generating game assets. Base URL: https://api.cortexstudio.dev/v1

Claude Code / Codex Skill

Install the Cortex skill in Claude Code or Codex CLI to let your AI coding assistant search, preview, and download assets automatically while you build.

Option 1: Claude Plugin (recommended)

Add the Cortex marketplace and install the plugin:

bash

claude plugin marketplace add bruno1308/cortex-skills

Install the Cortex Assets plugin:

bash

claude plugin install cortex-assets@cortex

Option 2: Manual install

Download the skill file directly into your project:

bash

mkdir -p .claude/skills/cortex-assets
curl -so .claude/skills/cortex-assets/SKILL.md \
  https://api.cortexstudio.dev/cortex-assets-skill.md

Set your API key

bash

export CORTEX_API_KEY="your_api_key_here"

Use it

Just describe what you need in your AI conversation. The skill teaches your assistant to search the library, show previews, and download assets on your behalf.

"I need pixel art sprites for a fantasy RPG — a knight, a dragon, and some treasure chests. Also grab some sword-clash sound effects."

The AI will search, present results with preview thumbnails, confirm your selection, and download the assets into your project.

Search and preview are free. Downloads cost 1–2 credits depending on asset type. The skill automatically checks your balance before downloading.

Authentication

All API requests require a Bearer token. Include your API key in the Authorization header. You can generate and manage API keys from your dashboard.

bash

curl https://api.cortexstudio.dev/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Requests without a valid API key return 401 Unauthorized.

Search

GET/v1/assets/search

Search the asset library. Returns up to 50 results by default. Search and preview are free — no credits consumed.

Parameter	Type	Required	Description
q	string	Yes	Search query (e.g. "fire icon", "forest ambience")
type	string	No	Asset type: image, audio, model, font
assetClass	string	No	Sub-class: sprite, tileset, sfx, music, etc.
style	string	No	Visual style: pixel-art, realistic, cartoon, etc.
category	string	No	Category tag, e.g. characters, ui, environment
theme	string	No	Theme tag, e.g. fantasy, sci-fi, medieval
license	string	No	Filter by license: cc0, mit, cc-by, etc.
limit	integer	No	Number of results (1–50, default 20)

bash

curl "https://api.cortexstudio.dev/v1/assets/search?q=fire+icon&type=image&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{
  "results": [
    {
      "id": "ast_01HXYZ123",
      "title": "Flame Icon",
      "type": "image",
      "assetClass": "sprite",
      "style": "pixel-art",
      "license": "cc0",
      "previewUrl": "https://cdn.cortexassets.com/preview/ast_01HXYZ123.webp",
      "creditCost": 1
    }
  ],
  "total": 42,
  "limit": 5,
  "offset": 0
}

Asset Metadata

GET/v1/assets/{id}

Retrieve full metadata for a single asset including all tags, dimensions, and license details.

bash

curl https://api.cortexstudio.dev/v1/assets/ast_01HXYZ123 \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{
  "id": "ast_01HXYZ123",
  "title": "Flame Icon",
  "description": "Animated pixel-art flame sprite, 32x32.",
  "type": "image",
  "assetClass": "sprite",
  "style": "pixel-art",
  "category": "effects",
  "theme": "fantasy",
  "license": "cc0",
  "licenseUrl": "https://creativecommons.org/publicdomain/zero/1.0/",
  "format": "png",
  "width": 32,
  "height": 32,
  "fileSize": 2048,
  "creditCost": 1,
  "previewUrl": "https://cdn.cortexassets.com/preview/ast_01HXYZ123.webp",
  "createdAt": "2025-11-15T08:22:00Z"
}

Preview

GET/v1/assets/{id}/preview

Returns a 302 redirect to a preview file. Always free — no credits consumed.

Images: Watermarked WebP thumbnail
Audio: Clipped MP3 (first 15 seconds)
3D models: Rendered PNG thumbnail
Fonts: PNG specimen card

bash

curl -L https://api.cortexstudio.dev/v1/assets/ast_01HXYZ123/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o preview.webp

Download

GET/v1/assets/{id}/download

Download the original asset file. Cost varies by type: images 1 cr, audio 1 cr, 3D models 2 cr, fonts 1 cr. Returns a 302 redirect to a signed URL (valid for 60 seconds). Returns 402 if your balance is insufficient.

bash

curl -L https://api.cortexstudio.dev/v1/assets/ast_01HXYZ123/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o flame-icon.png

json

// 402 Payment Required — insufficient credits
{
  "error": "insufficient_credits",
  "message": "You need 1 credit to download this asset. Current balance: 0.",
  "requiredCredits": 1,
  "currentBalance": 0
}

Generate Image

POST/v1/generate/image

Generate a new image using AI. Choose between OpenAI gpt-image-1.5 and Gemini gemini-3-pro-image-preview providers. Generated images are automatically ingested into the asset database and become searchable.

Parameter	Type	Required	Description
prompt	string	Yes	Text description of the image to generate (max 4000 chars)
provider	string	No	"openai" (default) or "gemini"
size	string	No	"1024x1024" (default), "1024x1536", "1536x1024", or "auto"
quality	string	No	"low" (3 cr), "medium" (5 cr, default), or "high" (8 cr). Gemini is always 4 cr.
background	string	No	"transparent", "opaque", or "auto" (OpenAI only)
n	integer	No	Number of images (1–4, default 1). Gemini always returns 1.
assetClass	string	No	Classification: sprite, tileset, background, icon, ui, portrait, item, effect, texture

bash

curl -X POST "https://api.cortexstudio.dev/v1/generate/image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "pixel art fire sword", "provider": "openai", "quality": "low", "background": "transparent"}'

json

{
  "images": [
    {
      "id": "a1b2c3d4-...",
      "url": "https://signed-url...",
      "revisedPrompt": "A detailed pixel art fire sword with..."
    }
  ],
  "provider": "openai",
  "model": "gpt-image-1.5",
  "creditsUsed": 3,
  "creditsRemaining": 42
}

Generated images are immediately available via their id in the Search, Metadata, Preview, and Download endpoints.

Edit Image

POST/v1/generate/image/edit

Edit an existing image using AI. Provide either a base64-encoded image or an asset ID from the database. Currently supports OpenAI only.

Parameter	Type	Required	Description
prompt	string	Yes	Edit instruction (e.g. "make the sword glow blue")
image	string	No	Base64-encoded image (max 10MB). Required if assetId not provided.
assetId	string	No	ID of an existing asset to edit. Required if image not provided.
size	string	No	"1024x1024" (default), "1024x1536", "1536x1024", or "auto"
quality	string	No	"low" (3 cr), "medium" (5 cr, default), or "high" (8 cr)
assetClass	string	No	Classification for the edited image

bash

curl -X POST "https://api.cortexstudio.dev/v1/generate/image/edit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "change the color to blue", "assetId": "a1b2c3d4-...", "quality": "low"}'

json

{
  "image": {
    "id": "e5f6g7h8-...",
    "url": "https://signed-url...",
    "revisedPrompt": null
  },
  "provider": "openai",
  "model": "gpt-image-1.5",
  "creditsUsed": 3,
  "creditsRemaining": 39
}

Account

GET/v1/account

Returns basic account information including your current credit balance.

bash

curl https://api.cortexstudio.dev/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{
  "email": "you@example.com",
  "creditBalance": 145,
  "createdAt": "2025-10-01T12:00:00Z"
}

Usage History

GET/v1/account/usage

Returns a paginated list of credit transactions (purchases and downloads).

Parameter	Type	Required	Description
limit	integer	No	Results per page (1–100, default 50)
offset	integer	No	Pagination offset (default 0)

bash

curl "https://api.cortexstudio.dev/v1/account/usage?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{
  "transactions": [
    {
      "id": "txn_01HABC999",
      "type": "download",
      "assetId": "ast_01HXYZ123",
      "assetTitle": "Flame Icon",
      "credits": -3,
      "balanceAfter": 145,
      "createdAt": "2026-01-10T14:33:00Z"
    },
    {
      "id": "txn_01HABC888",
      "type": "purchase",
      "credits": 500,
      "balanceAfter": 150,
      "createdAt": "2026-01-09T09:00:00Z"
    }
  ],
  "total": 24,
  "limit": 50,
  "offset": 0
}

Errors

All errors return JSON with error and message fields.

Status	Error code	Description
400	bad_request	Missing or invalid parameters.
401	unauthorized	Missing or invalid API key.
402	insufficient_credits	Not enough credits to complete the download.
404	not_found	The requested asset does not exist.
413	payload_too_large	Image data exceeds 10MB limit (edit endpoint).
429	rate_limited	Too many requests. Retry after the Retry-After header value.
502	generation_failed	The AI provider failed to generate the image. Credits are refunded.
503	provider_unavailable	The requested AI provider is not configured.