AI Providers

Previous Next

Retro Asset Studio generates images through an external AI provider that you connect with your own API key. You choose the provider per project from Project Settings > API Configuration.

In the current alpha, Google Gemini is the recommended and the only enabled provider. Hugging Face and OpenAI appear in the provider list but are disabled and labelled Coming soon; they cannot be selected and generation with them is blocked. See Coming soon below.

Retro Asset Studio is free. The only costs are whatever your provider charges you for generated images. Prompts, style guide text, and the reference images you select are sent to that provider and are subject to its terms of service. See Privacy & Data.

Overview

Provider Status in 0.1.0-alpha.1 Models Cost
Google Gemini Enabled, recommended gemini-3-pro-image (recommended default), gemini-2.5-flash-image, Custom Paid Google AI plan, billed per image by Google
Hugging Face Coming soon (disabled) Nano Banana 2 Space Will require a Hugging Face Pro subscription
OpenAI Coming soon (disabled) gpt-image-1, dall-e-3 Will be pay per image

The Gemini provider calls Google's Gemini API directly with a Google AI Studio key. It supports reference images, which the Character Designer, Asset Generator variants, Pose Editor, and Spritesheet Generator all rely on.

Requirements

  • A Google account
  • A Google AI Studio API key
  • A paid Google AI plan with billing enabled. Image generation models are not available on the free tier.

Billing is required

Using this provider with a free-tier API key results in a quota error (RESOURCE_EXHAUSTED). Enable billing on the Google Cloud project linked to your key at console.cloud.google.com before generating. Google bills you directly per generated image; check their current pricing.

Getting Your API Key

  1. Go to Google AI Studio and sign in with your Google account.
  2. Open Get API key: aistudio.google.com/apikey.
  3. Click Create API key.
  4. Select a Google Cloud project with billing enabled (or create one and enable billing).
  5. Copy the generated key. It starts with AIza.

Configuring in the App

  1. Open Project Settings from the sidebar.
  2. Scroll to API Configuration.
  3. Google Gemini (Image Generation) is selected by default. The Hugging Face and OpenAI options are greyed out and marked "Coming soon".
  4. Paste your API key into the Google AI API Key field.
  5. Choose an Image Generation Model:
    • gemini-2.5-flash-image: fast and cost-effective
    • gemini-3-pro-image: recommended default -- higher quality, higher cost
    • Custom…: enter any Gemini image model id manually
  6. Click Test Connection. This sends a real generation request to verify the key and model work.
  7. Click Save Settings.

Warning

Test Connection generates an actual image. It counts against your quota and billing.

Which model?

Model When to use it
gemini-2.5-flash-image Good quality, quick, cheapest of the three. Pick it when you generate many variations.
gemini-3-pro-image Default. Best detail and prompt following; more expensive and slower than Flash.
Custom For model ids Google releases after this version of the app. Enter the id exactly as listed in AI Studio.

Aspect Ratio Support

The app passes the selected aspect ratio directly to the Gemini API. Supported ratios: 1:1, 4:3, 3:4, 16:9, 9:16. The 21:9 ratio (ultra-wide backgrounds and Spritesheet Generator sheets) falls back to the API default.

Reference Images

Whenever the app attaches an image (a project reference with Use project reference image enabled, the source asset of a variant, the current frame and skeleton in the Pose Editor, or the character sprite in the Spritesheet Generator), it is sent together with the prompt. Gemini uses it as visual context, so results stay close to your existing art.

Errors and Rate Limits

Error Cause and fix
RESOURCE_EXHAUSTED / 429 with limit: 0 Image generation is not available on the free tier. Enable billing for the Google Cloud project linked to your key.
RESOURCE_EXHAUSTED / 429 with a retry delay You hit a per-minute or daily quota. Wait and retry.
404 model not found The model id is wrong, retired, or unavailable in your region. Pick another model from the dropdown.
SAFETY / response blocked The prompt or a reference image triggered Google's safety filters. Rephrase the prompt or use a different reference.
400 API key not valid The key was pasted incorrectly or has been deleted in AI Studio. Create a new one.
"No images returned" The model answered without an image. Simplify the prompt and try again.

Error messages appear as notifications in the app's bottom status bar, with a button to copy the exact text.

Coming soon: Hugging Face and OpenAI

Both providers are wired into the app but disabled in this alpha while their integrations are finished and tested. They show up in the provider list with a "Coming soon" label, cannot be selected, and any attempt to generate with them is blocked. They will be enabled in a later release; follow the Changelog.

Hugging Face (Nano Banana 2) will connect to the Nano Banana 2 Gradio Space on Hugging Face. It will require a Hugging Face account with an active Pro subscription and a Read access token (tokens start with hf_).

OpenAI (gpt-image-1 / DALL-E 3) will call OpenAI's Images API with an OpenAI API key from a platform account with billing enabled, offering gpt-image-1 (with reference-image editing) and dall-e-3.

Details for when it ships

Hugging Face

  • Create a Read token at huggingface.co/settings/tokens. Fine-grained tokens only need read access to repository contents; Inference permissions are not required because the app talks to a Space, not the Inference API.
  • The Space is Pro-gated: a free account sees "Access Denied – PRO users only".
  • The Space enforces a soft daily generation limit that resets every 24 hours, and it cold-starts after inactivity, so the first request can take a minute or more.

OpenAI

  • Create a key at platform.openai.com/api-keys; keys start with sk- and are shown once.
  • gpt-image-1 supports reference-image editing and may require organization verification in the OpenAI platform settings. dall-e-3 receives text only and ignores reference images.
  • Aspect ratios map to OpenAI sizes automatically (1:1 → 1024×1024; 16:9 and 4:3 → 1536×1024 or 1792×1024; 9:16 and 3:4 → 1024×1536 or 1024×1792).
  • Typical errors: 401 invalid key, insufficient_quota (billing), 429 rate limit, content_policy_violation (rephrase).

Switching Providers

When more providers are enabled, you will be able to change the provider at any time from Project Settings. The change takes effect on the next generation. Previously saved assets are not affected; they were generated with whatever provider was active at the time. Each project stores its own provider selection and credentials.

Security Notes

API keys are stored in the local database file:

%APPDATA%\Retro Asset Studio\data\app.json

They are encrypted with the Windows Data Protection API (DPAPI) through Electron's safeStorage, so they can only be read by your Windows user account on the same PC. Even so:

  • Do not share app.json or attach it to bug reports.
  • Exported .rasproj project files never contain keys. After importing a project you must re-enter them.
  • Rotate your API key if you suspect it has been exposed.
  • Each project has its own key. Switching projects switches credentials.

See Troubleshooting for help with connection errors and Privacy & Data for the full picture of what leaves your machine.

API Configuration Alpha Status