---
title: "Render BaZi Chart (SVG/PNG)"
method: POST
path: "/chinese/bazi/chart"
tags: ["chinese"]
---

# Render BaZi Chart (SVG/PNG)

`POST /chinese/bazi/chart`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/chinese/bazi/chart`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-OpenEphemeris-API-Key`
  - API key in header `X-API-Key`
  - API key in header `X-Service-Key`

Render the Four Pillars (八字 BaZi) as a finished chart image — the same computation as `POST /chinese/bazi`, drawn.

Returns the four pillars, the Day Master, the Five-Element (五行 Wu Xing) balance and the Yong Shen (用神, favourable element) as a single self-contained SVG, a base64 PNG, or a bare SVG blob — no client-side charting required.

**Output** — select with `visual_config.format`:
- `svg` (default): JSON envelope with the SVG string in `visual.data`.
- `png`: JSON envelope with base64 PNG in `visual.data`.
- `svg-raw`: a bare `image/svg+xml` body, no JSON envelope. Convenient for `<img src>`, but it carries no `calculation_metadata`, so the convention echo is unavailable in this mode.

**Conventions**: accepts the same five convention fields as `POST /chinese/bazi` (solar-term boundary, hour-pillar rule, zone handling), and echoes what was used in `calculation_metadata`.

**Metering**: 3 units per call — 1 for the pillar computation plus 2 for the visual render. `credits_used` reports the total actually charged.

## Headers

- `authorization` string, nullable
- `X-API-Key` string, nullable
- `X-OpenEphemeris-API-Key` string, nullable
- `apikey` string, nullable

## Request body

- BaZiChartRenderRequest: Birth date/time plus render options. Mirrors BaZiRequest and adds visual_config.
  - `datetime` string: ISO 8601 fallback when year/month/day are absent.
  - `day` integer: Day of month.
  - `day_boundary` 'zi_hour' | 'midnight': Day-pillar boundary convention. zi_hour rolls the day pillar at 23:00 (start of the Zi hour); midnight rolls it at 00:00.
  - `format` 'json' | 'llm': Response format: json | llm.
  - `hour` integer, nullable: Hour 0-23. Omit for a three-pillar chart.
  - `latitude` number, double: Birth latitude in decimal degrees (north positive). Required when true_solar_time is true. Otherwise optional: when BOTH coordinates are supplied and in range they resolve the birth timezone used to frame the solar-term boundary comparison (see `timezone`), which can change the year or month pillar for a birth near a boundary. Half a pair is still accepted and ignored.
  - `longitude` number, double: Birth longitude in decimal degrees (east positive). Required when true_solar_time is true. Otherwise optional: when BOTH coordinates are supplied and in range they resolve the birth timezone used to frame the solar-term boundary comparison (see `timezone`), which can change the year or month pillar for a birth near a boundary. Half a pair is still accepted and ignored.
  - `minute` integer: Birth minute (0–59). Defaults to 0, which reproduces the integer-hour behaviour exactly. Chinese hours (shí) are 2-hour blocks starting on odd hours, so a minute alone never moves the hour branch — it becomes load-bearing under true_solar_time, where the correction of up to ~±45 minutes is added to hour+minute/60 before the block and the 23:00 zi-hour tests are applied, and in the solar-term frame, where it shifts the birth instant by up to 59 minutes and can flip a Li Chun or Jié comparison for a birth within an hour of one.
  - `month` integer: Month, 1-12.
  - `timezone` TimezoneInput: Timezone input using IANA names or UTC offsets.
    - `fold_preference` 'earlier' | 'later': Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user.
    - `iana_name` string: IANA timezone name
    - `time_standard` 'auto' | 'standard' | 'daylight': How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used.
    - `utc_offset` number: UTC offset in hours
  - `true_solar_time` boolean: When true, the birth wall clock is converted to local apparent (true) solar time before the pillars are derived: the longitude correction relative to the timezone's standard meridian plus the equation of time. The correction can move the day - and therefore the day pillar and, through it, the hour stem - as well as the hour branch. The year and month pillars are compared at the true birth INSTANT and are unaffected by the correction, which transforms a clock reading rather than moving the birth. Requires latitude and longitude.
  - `visual_config` object: Render options.
    - `format` string: svg | png | svg-raw.
    - `size` integer: Pixel size; clamped to 1600.
    - `theme` string: Colour theme.
  - `year` integer: Gregorian year.
  - `year_boundary` 'lichun' | 'cny': Year-pillar boundary convention. lichun rolls the year pillar at the Lichun (立春) solar term, around 4 February; cny rolls it at Chinese New Year.

## Response `200`

Rendered BaZi chart. `svg` and `png` return the JSON envelope; `svg-raw` returns a bare SVG document.

- BaZiChartRenderResponse: Rendered chart plus the computed identity fields.
  - `calculation_metadata` object: Convention echo. Absent for visual_config.format = svg-raw.
  - `credits_used` integer: Total units charged (3).
  - `date` object: Echo of the date/time actually used.
  - `day_master` string: Day Master (日主) label.
  - `visual` object: Rendered artefact: type, format, content_type, data, credits_charged.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)