API Documentation

Convert any image to ASCII art with a single HTTP request.
Free, no API key required.

Endpoints

CLI Tool

Use yourascii directly from the terminal. No curl syntax needed.

curl -O https://yourascii.vercel.app/cli.js

# Show all commands and options
node cli.js --help

# Text to ASCII
node cli.js text "HELLO"
node cli.js text "GG" --font Doom
node cli.js text "WOW" --font Big --format html -o banner.html

# Image to ASCII
node cli.js convert photo.png
node cli.js convert photo.png --resolution 100 --colorMode colored
node cli.js convert photo.png --format svg -o output.svg

Limits & Security

/api/convert — Parameters

Two ways to send images:

/api/text — Parameters

Convert text into large ASCII banners using FIGlet fonts. Send as application/json.

Response Formats

{ "text": "...",
  "meta": { "cols": 80, "rows": 48 } }

Code Examples

curl -X POST https://yourascii.vercel.app/api/convert \
  -F "image=@photo.png" \
  -F "resolution=100" \
  -F "colorMode=mono"

curl -X POST https://yourascii.vercel.app/api/convert \
  -H "Content-Type: application/json" \
  -d '{"url": "https://i.imgur.com/your-image.jpg", "resolution": 80, "colorMode": "colored", "format": "html"}' \
  -o output.html

curl -X POST https://yourascii.vercel.app/api/text \
  -H "Content-Type: application/json" \
  -d '{"text": "HELLO", "font": "Doom"}'

const form = new FormData();
form.append("image", fileInput.files[0]);
form.append("resolution", "100");

const res = await fetch("https://yourascii.vercel.app/api/convert", {
  method: "POST",
  body: form,
});
const asciiText = await res.text();
console.log(asciiText);

import requests

with open("photo.png", "rb") as f:
    r = requests.post(
        "https://yourascii.vercel.app/api/convert",
        files={"image": f},
        data={"resolution": "100", "colorMode": "colored", "format": "json"},
    )
print(r.json())

curl -X POST https://yourascii.vercel.app/api/convert \
  -F "image=@photo.png" \
  -F "format=svg" -o output.svg

curl -X POST https://yourascii.vercel.app/api/convert \
  -F "image=@photo.png" \
  -F "format=animated" -o animated.html

Use Cases

Real-world ways developers use the yourascii API:

<!-- Add this to any HTML page -->
<input id="name" placeholder="Your name..." />
<button onclick="greet()">Generate</button>
<pre id="result" style="font-family:monospace"></pre>

<script>
async function greet() {
  const name = document.getElementById("name").value;
  const res = await fetch("https://yourascii.vercel.app/api/text", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text: "Hello " + name, font: "Doom" }),
  });
  document.getElementById("result").textContent = await res.text();
}
</script>

// Node.js Discord bot example
client.on("messageCreate", async (msg) => {
  if (msg.attachments.size > 0) {
    const imageUrl = msg.attachments.first().url;
    const res = await fetch("https://yourascii.vercel.app/api/convert", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ url: imageUrl, resolution: 50 }),
    });
    const ascii = await res.text();
    msg.reply("```\n" + ascii + "\n```");
  }
});

# Generate a banner for your README
curl -X POST https://yourascii.vercel.app/api/text \
  -H "Content-Type: application/json" \
  -d '{"text": "My Project", "font": "Big"}'

# Output:
#  __  __         ____            _           _
# |  \/  |_   _  |  _ \ _ __ ___ (_) ___  ___| |_
# | |\/| | | | | | |_) | '__/ _ \| |/ _ \/ __| __|
# | |  | | |_| | |  __/| | | (_) | |  __/ (__| |_
# |_|  |_|\__, | |_|   |_|  \___// |\___|\___|\___|
#          |___/                |__/

import requests, os

for filename in os.listdir("./photos"):
    with open(f"./photos/{filename}", "rb") as f:
        r = requests.post(
            "https://yourascii.vercel.app/api/convert",
            files={"image": f},
            data={"resolution": "80", "format": "html"},
        )
    with open(f"./output/{filename}.html", "w") as out:
        out.write(r.text)
    print(f"Converted {filename}")

const [ascii, setAscii] = useState("");

async function handleUpload(file) {
  const form = new FormData();
  form.append("image", file);
  form.append("resolution", "60");
  form.append("colorMode", "colored");
  form.append("format", "html");

  const res = await fetch("https://yourascii.vercel.app/api/convert", {
    method: "POST", body: form,
  });
  setAscii(await res.text());
}

return <div dangerouslySetInnerHTML={{ __html: ascii }} />;

Error Codes

Example Outputs

Real outputs generated with the yourascii engine at various resolutions and color modes.