Chart Image

Endpoint POST https://starsapi.com/api/v3/western/natal/chart-image
GET https://starsapi.com/api/v3/western/natal/chart-image?key=...&expires=...&token=...

Overview

Returns a direct PNG image of the natal wheel chart (not JSON). Two access modes:

POST — send birth data + API key, receive PNG directly. Good for server-side generation.
GET — use a signed URL from natal/chart. No API key needed. Good for embedding in <img> tags and sharing.

Image specs: 1100×1100 pixels, PNG RGBA, typically 250–300 KB. Shows zodiac wheel with house cusps, planet glyphs, degree markers, and color-coded aspect lines.

Authentication

Mode	Authentication
POST	API key via `X-Api-Key` header or request body.
GET	HMAC-signed URL parameters (`key`, `expires`, `token`). No API key needed.

POST mode (direct)

Send birth data as JSON, receive PNG:

Field	Type	Required	Description
`year`	integer	Yes	Birth year (1800–2400).
`month`	integer	Yes	Birth month (1–12).
`day`	integer	Yes	Birth day.
`hour`	integer	Yes	Birth hour (0–23).
`minute`	integer	Yes	Birth minute (0–59).
`second`	integer	No	Default `0`.
`latitude`	number	Yes	Decimal degrees (−90 to 90).
`longitude`	number	Yes	Decimal degrees (−180 to 180).
`timezone`	string	Yes	IANA timezone.
`house_system`	string	No	Default `placidus`.
`show_aspects`	boolean	No	Draw aspect lines on chart. Default `true`.
`major_aspects_only`	boolean	No	Only draw major aspect lines. Default `true`.
`name`	string	No	Native’s name (top-left corner).
`place`	string	No	Birth place (separate line below date/time).
`branding`	string	No	Attribution line below birth info.
`center_text`	string	No	Chart center text. Empty string = no center text.
`birth_info`	string	No	Custom birth info line. If omitted, auto-generated as `May 20, 1990, 14:30 IST`.
`birth_place`	string	No	Explicit place line. Falls back to `place` if not set.

GET mode (signed URL)

Use the chart_url returned by natal/chart:

<img src="https://starsapi.com/api/v3/western/natal/chart-image?key=abc123&expires=1781760879&token=def456" />

Param	Description
`key`	Cache key (MD5 hash of birth data + options).
`expires`	Unix timestamp when the URL expires (24 hours from generation).
`token`	HMAC-SHA256 signature.

The GET mode uses cached chart data and branding from the original natal/chart call. The branding options you sent when generating the signed URL are baked into the cache.

Branding

See natal/chart branding options for the full layout. Same options apply in POST mode. In GET mode, branding is taken from the cached data.

Caching

Generated PNGs are cached on disk for 24 hours. The X-Cache response header indicates HIT (served from cache) or MISS (freshly rendered). Cache keys include birth data and branding options, so the same birth data with different branding produces separate cached images.

Errors

Errors are returned as JSON (not PNG) with appropriate HTTP status codes:

HTTP	Code	Cause
400	`MISSING_FIELD`	Required field absent (POST mode).
400	`INVALID_JSON`	Request body is not valid JSON.
400	`VALIDATION_ERROR`	Missing signed URL parameters (GET mode).
403	`TOKEN_EXPIRED`	Signed URL has expired (GET mode).
403	`INVALID_TOKEN`	HMAC signature mismatch (GET mode).
404	`CACHE_MISS`	Chart data not in cache — regenerate via `natal/chart`.
500	`EPHEMERIS_ERROR`	Swiss Ephemeris computation failed.
500	`CHART_ERROR`	Image generation failed.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/western/natal/chart-image" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "house_system": "placidus",
        "node_type": "true",
        "name": "Priya",
        "place": "New Delhi",
        "branding": "Powered by MyAstroApp.com",
        "center_text": "MyAstroApp",
        "show_aspects": true,
        "major_aspects_only": false
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/western/natal/chart-image',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      year: 1990,
      month: 5,
      day: 20,
      hour: 14,
      minute: 30,
      second: 0,
      latitude: 28.6139,
      longitude: 77.209,
      timezone: 'Asia/Kolkata',
      house_system: 'placidus',
      node_type: 'true',
      name: 'Priya',
      place: 'New Delhi',
      branding: 'Powered by MyAstroApp.com',
      center_text: 'MyAstroApp',
      show_aspects: true,
      major_aspects_only: false
    })
  }
);
const result = await response.json();

if (result.success) {
  console.log(result.data);
}

import requests
import os

response = requests.post(
    'https://starsapi.com/api/v3/western/natal/chart-image',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    json={
        'year': 1990,
        'month': 5,
        'day': 20,
        'hour': 14,
        'minute': 30,
        'second': 0,
        'latitude': 28.6139,
        'longitude': 77.209,
        'timezone': 'Asia/Kolkata',
        'house_system': 'placidus',
        'node_type': 'true',
        'name': 'Priya',
        'place': 'New Delhi',
        'branding': 'Powered by MyAstroApp.com',
        'center_text': 'MyAstroApp',
        'show_aspects': True,
        'major_aspects_only': False
    }
)
result = response.json()

if result['success']:
    print(result['data'])

<?php
$payload = [
    'year' => 1990,
    'month' => 5,
    'day' => 20,
    'hour' => 14,
    'minute' => 30,
    'second' => 0,
    'latitude' => 28.6139,
    'longitude' => 77.209,
    'timezone' => 'Asia/Kolkata',
    'house_system' => 'placidus',
    'node_type' => 'true',
    'name' => 'Priya',
    'place' => 'New Delhi',
    'branding' => 'Powered by MyAstroApp.com',
    'center_text' => 'MyAstroApp',
    'show_aspects' => true,
    'major_aspects_only' => false,
];

$ch = curl_init('https://starsapi.com/api/v3/western/natal/chart-image');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . getenv('STARSAPI_KEY'),
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success']) {
    print_r($data['data']);
}

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<Map<String, dynamic>> getAscendant() async {
  final response = await http.post(
    Uri.parse('https://starsapi.com/api/v3/western/natal/chart-image'),
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'year': 1990,
      'month': 5,
      'day': 20,
      'hour': 14,
      'minute': 30,
      'second': 0,
      'latitude': 28.6139,
      'longitude': 77.209,
      'timezone': 'Asia/Kolkata',
      'house_system': 'placidus',
      'node_type': 'true',
      'name': 'Priya',
      'place': 'New Delhi',
      'branding': 'Powered by MyAstroApp.com',
      'center_text': 'MyAstroApp',
      'show_aspects': true,
      'major_aspects_only': false,
    }),
  );
  return jsonDecode(response.body);
}

import Foundation

func getAscendant() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/western/natal/chart-image"
    )!)
    request.httpMethod = "POST"
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = """
        {
            "year": 1990,
            "month": 5,
            "day": 20,
            "hour": 14,
            "minute": 30,
            "second": 0,
            "latitude": 28.6139,
            "longitude": 77.209,
            "timezone": "Asia/Kolkata",
            "house_system": "placidus",
            "node_type": "true",
            "name": "Priya",
            "place": "New Delhi",
            "branding": "Powered by MyAstroApp.com",
            "center_text": "MyAstroApp",
            "show_aspects": true,
            "major_aspects_only": false
        }
        """.data(using: .utf8)

    let (data, _) = try await URLSession.shared.data(for: request)
    return try JSONSerialization.jsonObject(with: data) as! [String: Any]
}

import okhttp3.*
import org.json.JSONObject

val client = OkHttpClient()
val JSON = "application/json; charset=utf-8".toMediaType()

fun getAscendant(callback: (JSONObject) -> Unit) {
    val payload = """
    {
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "house_system": "placidus",
        "node_type": "true",
        "name": "Priya",
        "place": "New Delhi",
        "branding": "Powered by MyAstroApp.com",
        "center_text": "MyAstroApp",
        "show_aspects": true,
        "major_aspects_only": false
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/western/natal/chart-image")
        .addHeader("X-Api-Key", "YOUR_API_KEY")
        .post(payload.toRequestBody(JSON))
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onResponse(call: Call, response: Response) {
            callback(JSONObject(response.body!!.string()))
        }
        override fun onFailure(call: Call, e: java.io.IOException) {
            e.printStackTrace()
        }
    })
}

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    payload, _ := json.Marshal(map[string]interface{}{
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "house_system": "placidus",
        "node_type": "true",
        "name": "Priya",
        "place": "New Delhi",
        "branding": "Powered by MyAstroApp.com",
        "center_text": "MyAstroApp",
        "show_aspects": true,
        "major_aspects_only": false,
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/western/natal/chart-image",
        bytes.NewBuffer(payload))
    req.Header.Set("X-Api-Key", os.Getenv("STARSAPI_KEY"))
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result["data"])
}

require 'net/http'
require 'json'

uri = URI('https://starsapi.com/api/v3/western/natal/chart-image')
payload = {
  'year' => 1990,
  'month' => 5,
  'day' => 20,
  'hour' => 14,
  'minute' => 30,
  'second' => 0,
  'latitude' => 28.6139,
  'longitude' => 77.209,
  'timezone' => 'Asia/Kolkata',
  'house_system' => 'placidus',
  'node_type' => 'true',
  'name' => 'Priya',
  'place' => 'New Delhi',
  'branding' => 'Powered by MyAstroApp.com',
  'center_text' => 'MyAstroApp',
  'show_aspects' => true,
  'major_aspects_only' => false
}

req = Net::HTTP::Post.new(uri)
req['X-Api-Key'] = ENV['STARSAPI_KEY']
req['Content-Type'] = 'application/json'
req.body = payload.to_json

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
res = http.request(req)

data = JSON.parse(res.body)
puts data['data'] if data['success']

200 RESPONSE

Returns: image/png (binary)
Content-Type: image/png
Content-Length: 263472
Cache-Control: public, max-age=86400
X-API-Version: 3.0
X-Cache: MISS

(PNG binary data — 1100×1100 RGBA)