Skip to content
HiAPI Docs
HiAPI
Playground Get API Key
English
English 中文

Ideogram V4 API

POST /v1/tasks

All models are called through the Unified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model name ideogram-v4
Type Image generation (text-to-image)
Endpoint POST /v1/tasks
Pricing See HiAPI Pricing

Ideogram V4: the typography specialist — best-in-class text accuracy for logos, posters and signage, with TURBO/BALANCED/QUALITY tiers priced per image.

Production guidance

Production guidance
  • For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
  • GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
  • Use callback.when=final. Both success and fail are terminal states, so your service should deduplicate by taskId.

Best suited for

Logos & wordmarks

Custom wordmarks, monograms and icon-in-letter tricks (a coffee bean inside the ampersand) in one pass, with vector-clean edges.

promptrendering_speed
Posters & layouts

Complete layouts with title, subtitle and multi-line copy — best-in-class spelling accuracy, strongest in English.

prompt
Signage & marquees

Neon tubes, channel letters, backlit boards — materialized lettering renders reliably.

prompt
Three speed tiers

Iterate on TURBO, deliver on QUALITY — a ~3x price spread for flexible budgets.

rendering_speed

Request parameters

model string required

Fixed value ideogram-v4.

example ideogram-v4
input object required

Business parameters. Put Ideogram V4-specific configuration here.

prompt string required

Text description of the image. Spell out any text to render — accurate typography is this model's specialty.

aspect_ratio enum optional

Output aspect ratio (preset sizes around 1MP).

default 1:1 enum: 1:116:94:39:163:4
rendering_speed enum required

TURBO is fastest and cheapest, QUALITY is the most detailed. Price differs per tier.

default BALANCED enum: TURBOBALANCEDQUALITY
output_format enum optional

Output image format.

default jpeg enum: jpegpng
seed integer optional

Random seed for reproducible generation.

callback object optional

Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.

url string required

Required when callback is set; HTTPS URL that receives terminal task notifications.

example https://your-domain.com/hiapi/callback
when enum optional

Callback trigger timing. Use final.

default final enum: final

Example requests

Cinema marquee (QUALITY)

Dimensional glowing letters, symmetric layout — delivery tier.

Request body
{
  "model": "ideogram-v4",
  "input": {
    "prompt": "An art deco cinema marquee at night: the words GRAND PALACE THEATRE in glowing gold channel letters, NOW SHOWING on a smaller board below, brass and burgundy facade, warm bulbs, all lettering accurate and crisp, symmetrical composition",
    "aspect_ratio": "16:9",
    "rendering_speed": "QUALITY"
  }
}
Coffee wordmark (TURBO)

Cheapest way to draft a logo.

Request body
{
  "model": "ideogram-v4",
  "input": {
    "prompt": "A minimalist coffee shop logo design: the words BREW & CO in an elegant custom serif wordmark, a subtle coffee bean integrated into the ampersand, warm espresso brown on cream background, centered composition, premium brand identity, vector-clean edges",
    "aspect_ratio": "1:1",
    "rendering_speed": "TURBO"
  }
}
Kyoto travel poster (TURBO)

Hand-lettered retro title with flat illustration.

Request body
{
  "model": "ideogram-v4",
  "input": {
    "prompt": "A vintage travel poster of Kyoto: the word KYOTO in large hand-lettered retro type at the top, subtitle JAPAN below, a pagoda among maple trees in flat mid-century illustration style, autumn palette, all lettering accurate",
    "aspect_ratio": "3:4",
    "rendering_speed": "TURBO"
  }
}

Getting the result

  1. The response returns a taskId immediately without waiting for generation to finish.
  2. In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
  3. When status=success, download the generated image from output[].url.
  4. When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.

FAQ

What separates the three rendering_speed tiers?

TURBO is fastest and cheapest for iteration; BALANCED is the middle ground; QUALITY has the finest detail at roughly 3x the TURBO price for final delivery. Each tier is priced per image — see the pricing page. View pricing

How good is non-English text?

Ideogram excels at English typography with best-in-class spelling. It can render Chinese but less reliably — for Chinese-first layouts, use seedream-5.0-lite or qwen-image-2.0-pro instead.

How do I prompt for reliable lettering?

Frame the exact wording in caps or quotes (e.g. the words BREW & CO) and add "all lettering accurate". Fewer total words per image is more reliable.

How do I get the generated image?

The request returns a taskId immediately. When the task reaches a terminal state, download the image from output[].url. In production, pass callback.url at the top level of the request body instead of polling.

Next steps