Ideogram AI Ideogram Vector Text To Vector API Documentation

Ideogram AI Ideogram Vector Text To Vector API Documentation

Playground

Ideogram Vector Text-to-Vector creates editable SVG graphics from text prompts and optional reference images, with flexible aspect ratios and three quality levels. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Ideogram Vector Text-to-Vector generates editable SVG graphics from text descriptions, with optional reference images for additional visual guidance. Create logos, icons, illustrations, lettering, and other scalable artwork that stays sharp at any size.

Why Choose This?

• Editable SVG output — Continue refining the result in a vector editor.
• Reference image support — Add up to 5 images to guide the design.
• Flexible framing — Choose from a wide range of aspect ratios.
• Three quality levels — Select low, medium, or high depending on your quality needs.
• Scalable graphics — Generate artwork suitable for digital, print, branding, and interface workflows.

Parameters

How to Use

1. Write a prompt — Describe the subject, shapes, colors, composition, style, and any text.
2. Add references optional — Upload up to 5 images when visual guidance is needed.
3. Choose framing — Select the desired aspect ratio.
4. Choose quality — Use low, medium, or high.
5. Submit — Generate and retrieve the SVG.

Pricing

Reference images affect pricing only when quality=high.

The number of reference images does not add additional charges within the supported limit.

Best Use Cases

• Logos and brand marks — Create scalable branding concepts and symbols.
• Icons and interface graphics — Generate clean vector assets for digital products.
• Posters and lettering — Produce graphic layouts with scalable text and shapes.
• Illustrations — Create vector artwork for editorial, marketing, and creative projects.
• Print assets — Generate graphics that remain sharp at different output sizes.

Pro Tips

• Describe the desired shapes, colors, composition, and visual style clearly.
• Put text that should appear in the artwork inside quotation marks.
• Use reference images that clearly show the visual elements you want to retain.
• Place the most important reference image first.
• Use high quality when greater detail is needed.

Notes

• Each request generates one SVG.
• Reference images are optional.
• Up to 5 reference images are supported.
• Each reference image can be up to 10 MB.
• Supported aspect ratios are 1:1, 1:4, 1:3, 1:2, 9:16, 10:16, 2:3, 3:4, 4:5, 5:4, 4:3, 3:2, 16:10, 16:9, 2:1, 3:1, and 4:1.
• Review text and fine details before using the generated artwork in production.

Related Models

• Ideogram Vector Text-to-Vector — Generate editable SVG graphics from text prompts.
• Ideogram Vector Image-to-Vector — Convert and reinterpret reference images as editable vector graphics.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "aspect_ratio": "1:1",
  "quality": "medium"
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/ideogram-ai/ideogram-vector/text-to-vector" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted)
      printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
      printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters