ascii.im tutorial

1Quick start: make your first ASCII art in 60 seconds#

ascii.im is an ASCII art generator that paints with your own words. You describe an object, an AI model draws it, and the app repaints the result entirely out of the characters in your prompt — so the picture is literally made of the sentence you typed.

1. Step 1

   Describe the object

   Type a short noun phrase in the search box on the home page, for example “a red apple”. Keep it concrete: one subject, one or two attributes.

2. Step 2

   Watch the pigments appear

   Under the box you immediately see the shade ramp. Every distinct character in your prompt becomes one pigment, sorted from lightest to darkest by how much ink the glyph puts on the page.

3. Step 3

   Open the studio

   Press Enter or click “Draw it”. Your prompt carries over to /studio, where the full-resolution controls live.

4. Step 4

   Pick an image provider

   Choose “Built-in placeholder (offline)” if you have no API key yet — it costs no quota and lets you exercise the whole pipeline. Otherwise pick any configured provider.

5. Step 5

   Generate and refine

   Press “Generate image”. Then tune columns, dithering and background handling until the text pixel art reads the way you want.

Back to top ↑

2What is text pixel art (and how is it different from ASCII art)?#

Text pixel art is a form of ASCII art in which the shade ramp is not fixed but derived from a source string. Instead of the classic “ .:-=+*#%@” ladder, the characters come from your prompt, and their order comes from measured stroke density rather than from a hand-written table.

That single change makes the medium personal. The prompt “一个红苹果” gives five Chinese glyphs with five different ink values, so the apple you get back is painted with 一、个、红、苹、果 — the object and its caption are the same material. In traditional ASCII art the alphabet is a generic commodity; here it is the content.

Back to top ↑

3How do you write a prompt that produces good ASCII art?#

A prompt in ascii.im does two jobs at once. It tells the image model what to draw, and it supplies the pigment set. Good prompts therefore optimise for two things: a clear subject, and a range of stroke densities among the characters.

• Name one subject. “a red apple” beats “still life with fruit, a bowl and morning light”.
• Aim for five to twelve distinct characters. Fewer than four shades looks flat; more than forty adds noise.
• Mix light and heavy glyphs. Words that combine thin and dense strokes produce the richest ramp.
• Avoid long strings of the same character — repeated glyphs collapse into one pigment after de-duplication.
• Add one style word if you want a specific look: “a red apple, studio lighting, white background”.

Back to top ↑

4How does the pigment palette decide which character is darker?#

Ink is the amount of black a glyph puts on the page: the character is rasterised inside a fixed em box and the covered pixel ratio is measured. A thin glyph such as “一” or “i” scores near 0.04–0.12; a dense glyph such as “果” or “M” reaches 0.35–0.45. Sorting characters by ink produces a light-to-dark shade ramp with no manual tuning, and that per-glyph density figure is what makes the ramp reproducible across fonts and machines.

Because ink measures geometry rather than identity, the same rule works for every writing system. This is why ascii.im can generate ASCII art from Chinese, Japanese, Korean, Cyrillic, Greek, Arabic, Hebrew, Thai or Devanagari prompts without maintaining per-language lookup tables.

• Drag any swatch in the ramp to reorder it by hand — useful when ink is only estimated.
• “Add glyphs” appends your own characters to the palette.
• “Use a space as the lightest shade” gives highlights room to breathe.
• “Minimum shades” tops the ramp up to a target depth.

Back to top ↑

5What pixel resolution should you use for ASCII art?#

Resolution in ascii.im is the number of character columns across the image. Rows are derived automatically: cols × cell aspect × (image height / image width), where the cell aspect is the measured advance ratio of your glyphs. That keeps the artwork physically proportional instead of squashed.

If the subject reads clearly at Draft, stop there — larger grids cost more render time and larger files without adding meaning. Increase resolution when fine structure matters: hair, foliage, lettering, or fabric texture.

Back to top ↑

6Why does my ASCII art look banded, and how does dithering fix it?#

Quantisation maps a continuous brightness to one of a few shades. With five shades and a smooth gradient, that mapping produces hard edges — banding. Dithering perturbs the mapping with a spatially distributed error so the eye integrates neighbouring cells and perceives intermediate tones.

• Start with Floyd–Steinberg at default strength for any photographic source.
• Lower the strength if the texture starts to fight the letterforms.
• Switch to Bayer when you want a deliberately graphic, halftone feel.
• Turn dithering off when your palette already has ten or more shades.

Back to top ↑

7How do you handle the background and contrast of ASCII art?#

Background handling decides whether empty space is painted or left blank. “Keep” preserves the full tonal range including the backdrop; “Knock out” floods from the four borders, removes the background and feathers the edge so the subject sits on nothing — which is usually what you want for logos, products and stickers.

• Cutout tolerance: how aggressively a pixel is treated as background. Raise it for busy scenes, lower it when the subject has soft edges.
• Edge feather: the number of cells blended at the boundary. One or two cells removes the “staircase” look.
• Keep the background on when the backdrop carries information — a sky, a wall, a gradient.
• Use dark-on-light for printing, light-on-dark for screens and slides.

Contrast, brightness and gamma are applied before quantisation, so they change which shades get used. If your text pixel art looks muddy, widening contrast usually helps more than adding glyphs.

Back to top ↑

8Which image provider should you use for ASCII art?#

ascii.im separates drawing from painting. Every provider is an AI image generator that supplies only the source photograph; the text pixel conversion is done locally by the same pipeline, so switching providers changes the picture but never the medium. Free-tier providers are open to everyone, while pro-tier ones require an account and draw on your free generations.

• Asynchronous providers submit a task and poll for the result; they take longer but handle larger images.
• Synchronous providers return in one round trip — better for rapid iteration.
• Aspect ratio is requested from the model where supported, so the grid stays square or wide as you choose.

Back to top ↑

9How do you supply API keys safely?#

Credentials never leave the request lifecycle. They are read from server environment variables when present, otherwise supplied per session from the browser; they are never written to disk and never logged. That single security rule is what makes a shared deployment safe: no key ever reaches the client.

1. Copy .env.example to .env.local.
2. Fill in the variables for the providers you want (for example DASHSCOPE_API_KEY).
3. Restart the server. The provider panel will report “Ready”.
4. For a quick test without a restart, use the session key field instead. Keys stay in memory unless you tick “Remember keys in this browser”, which stores them in localStorage — clearable at any time.

Generated images are proxied through the server and returned as same-origin data URLs. This keeps the browser canvas free of cross-origin tainting and means expiring vendor URLs never break an in-progress export.

Back to top ↑

10How do you export ASCII art as text, SVG or PNG?#

The studio exports the current artwork in three formats. All three are produced in the browser from the same cell grid, so what you see is exactly what you get.

• SVG uses absolute per-glyph x positions, so layout does not drift between fonts and machines.
• Plain text is strict for all-CJK or all-Latin prompts; mixed scripts can show slight alignment drift in proportional text views.
• Copy text puts the artwork on the clipboard directly.

Back to top ↑

11Can you make ASCII art in Chinese, Japanese, Arabic or Korean?#

Any writing system works, because ink measures how much of a square cell a glyph covers rather than which character it is. Unicode ASCII art is therefore not a special case but the default behaviour: Latin, Han, kana, hangul, Cyrillic, Greek, Arabic, Hebrew, Thai and Devanagari prompts all produce usable shade ramps. That is what makes multi-language ASCII art practical — there are no per-language tables to maintain.

• Case folding: in bicameral scripts (Latin, Cyrillic, Greek) upper and lower case collapse into one pigment, so “A” and “a” are not counted twice.
• Grapheme clusters: Thai and Devanagari combining marks are segmented as single units, so a vowel sign never becomes a standalone pigment.
• Cell aspect: CJK glyphs are square, Latin glyphs roughly half as wide. The grid derives its row count from the measured aspect, so proportions stay correct.
• Font stack: each script resolves to a font stack that actually contains its glyphs, with a system monospace fallback.

Right-to-left scripts such as Arabic are handled at the layout level: the document direction flips and the CSS uses logical properties, so spacing and inset behave correctly without duplicating rules.

Back to top ↑

12ASCII art FAQ and troubleshooting#

This section collects the most common problems and their fixes, in roughly the order people hit them: flat shade ramps, missing providers, estimated ink, misaligned text output and failed generations. Each answer states what actually happens inside the app rather than what you might expect.

Back to top ↑