starflask

Command-line interface for the Starflask API. Built for AI agents and automation — every command outputs machine-readable JSON.

Install

npm install -g starflask

Or run directly:

npx starflask

Quick Start

# Store your API key
starflask auth set sk-your-key-here

# Check your account
starflask me

# Generate an image
starflask jobs create image --payload '{"prompt": "a fox in a forest"}'

# Wait for it to finish
starflask jobs wait <job-id>

Authentication

API keys can be provided three ways (highest priority first):

1. Flag: --api-key sk-...
2. Environment variable: STARFLASK_API_KEY=sk-...
3. Credentials file: starflask auth set sk-... (stored in ~/.starflask/credentials.json)

The API URL defaults to https://starflask.com and can be overridden the same way via --api-url or STARFLASK_API_URL.

starflask auth set sk-abc123          # save key
starflask auth get                    # show masked key
starflask auth remove                 # delete stored credentials

Commands

me — Account Info

starflask me
# {"ok":true,"id":"...","email":"[email protected]","plan":"free","credits":500}

jobs — Create and Monitor Jobs

Create media generation and processing jobs, then poll for results.

starflask jobs create <type> --payload '{...}'
starflask jobs get <id>
starflask jobs wait <id> [--interval 2] [--timeout 300]

Job Types

| Type | Description | Key Params | |------|-------------|------------| | image | Generate an image from a prompt | prompt, aspect_ratio | | video | Convert between media formats | video_url, target_format, fps, max_width | | upscale | Upscale an image (2x or 4x) | image_url, scale, creativity | | remove_bg | Remove image background | image_url | | cartoonify | Cartoonify an image | image_url | | vectorize | Convert an image to SVG | image_url | | vector | Generate SVG from a text prompt | mode, prompt |

Examples

Generate an image:

starflask jobs create image --payload '{"prompt": "a tiny red fox sitting on a mushroom"}'

Convert GIF to WebP:

starflask jobs create video --payload '{
  "structured_data": {
    "params": {
      "video_url": "https://example.com/animation.gif",
      "target_format": "webp",
      "fps": 15,
      "max_width": 640
    }
  }
}'

Convert MP4 to GIF (first 5 seconds):

starflask jobs create video --payload '{
  "structured_data": {
    "params": {
      "video_url": "https://example.com/clip.mp4",
      "target_format": "gif",
      "fps": 12,
      "max_width": 480,
      "start_time": 0,
      "duration": 5
    }
  }
}'

Upscale an image 4x:

starflask jobs create upscale --payload '{
  "structured_data": {
    "params": {
      "image_url": "https://example.com/photo.jpg",
      "scale": 4,
      "creativity": 0.5
    }
  }
}'

Remove background:

starflask jobs create remove_bg --payload '{
  "structured_data": {
    "params": {
      "image_url": "https://example.com/photo.jpg"
    }
  }
}'

Generate SVG from text:

starflask jobs create vector --payload '{
  "structured_data": {
    "params": {
      "mode": "generate",
      "prompt": "a minimalist mountain logo"
    }
  }
}'

Wait for a job to complete:

starflask jobs wait <id> --timeout 120 --interval 3

Job statuses progress: pending → processing → completed | failed

media — Upload, Retrieve, and Download Files

starflask media upload <file>
starflask media get <id>
starflask media download <id> --output <path>

Upload limits: Images 25MB, Video 100MB, Data files 5MB.

Upload a file and download the result of a conversion:

# Upload a GIF
UPLOAD=$(starflask media upload ./animation.gif)
MEDIA_ID=$(echo $UPLOAD | jq -r .id)

# Get a fresh presigned URL for the upload
URL=$(starflask media get $MEDIA_ID | jq -r .url)

# Convert to WebP
JOB=$(starflask jobs create video --payload "{
  \"structured_data\": {
    \"params\": {\"video_url\": \"$URL\", \"target_format\": \"webp\"}
  }
}")
JOB_ID=$(echo $JOB | jq -r .id)

# Wait and download
starflask jobs wait $JOB_ID
starflask media download $MEDIA_ID --output ./animation.webp

api-keys — Manage API Keys

starflask api-keys list
starflask api-keys create --name "CI pipeline"
starflask api-keys delete <id>

Maximum 5 active API keys per account.

Output Format

Every command outputs a single JSON object to stdout:

{"ok": true, "id": "...", ...}

On error:

{"ok": false, "error": "description of what went wrong"}

Exit code is 0 on success, 1 on failure. This makes it easy to parse in scripts and AI agent tool chains.

Use with AI Agents

The CLI is designed for non-interactive use. Example with Claude Code:

# Set up auth via environment variable
export STARFLASK_API_KEY=sk-your-key

# Agent can now run commands and parse JSON output
starflask me
starflask jobs create image --payload '{"prompt":"..."}'
starflask jobs wait <id>

Help

starflask --help              # overview
starflask jobs --help          # detailed job types and examples
starflask media --help         # upload/download details
starflask auth --help          # credential management
starflask api-keys --help      # key management