Chart Image

Endpoint POST https://starsapi.com/api/v3/vedic/natal/chart-image

Returns signed, time-limited image URLs for the D1 (Rashi) birth chart in both North Indian and South Indian styles. The URLs point to rendered chart images that can be embedded directly in an <img> tag or downloaded. Each URL includes a secure token and expiry — no additional authentication is needed to fetch the image.

This is a convenience endpoint for apps that need a visual chart without client-side rendering. For the underlying planet and house data, call /natal/planets or /natal/planets-in-houses.

Authentication

Required. Three methods accepted:

Method	Example
Header (recommended)	`X-Api-Key: am_live_xxxxxxxxxxxx`
Bearer	`Authorization: Bearer am_live_xxxxxxxxxxxx`
Query	`?api_key=am_live_xxxxxxxxxxxx`

See authentication for security considerations.

Request body

Send a JSON object with Content-Type: application/json. All core fields are required.

Field	Type	Required	Description
`year`	integer	Yes	Birth year, 4-digit (e.g. `1990`).
`month`	integer	Yes	Birth month, `1`–`12`.
`day`	integer	Yes	Day of month, `1`–`31`.
`hour`	integer	Yes	Hour in 24-hour local clock time, `0`–`23`.
`minute`	integer	Yes	Minute, `0`–`59`.
`second`	integer	No	Second, `0`–`59`. Default `0`.
`latitude`	number	Yes	Signed decimal degrees, −90…90. Positive = North.
`longitude`	number	Yes	Signed decimal degrees, −180…180. Positive = East.
`timezone`	string	Yes	IANA timezone identifier.
`name`	string	No	Use `/vedic/birth-details` to retrieve.
`place`	string	No	Use `/vedic/birth-details` to retrieve.
`ayanamsa`	string	No	Default `lahiri`. Full list →
`node_type`	string	No	`mean` (default) or `true`.

Response shape

A single data.chart object with chart metadata and two signed image URLs.

Field	Type	Description
data.chart
`code`	string	Divisional chart code (always `D1` for this endpoint).
`name`	string	Chart name (always `Rashi`).
data.chart.images
`north`	string (URL)	Signed URL for the North Indian style chart image. Token-authenticated, time-limited.
`south`	string (URL)	Signed URL for the South Indian style chart image. Token-authenticated, time-limited.

Image URLs are time-limited. Each URL contains an expires timestamp and a token. The image can be fetched directly (no API key needed) but will return 403 after expiry. Generate fresh URLs by calling this endpoint again.

Use cases

Instant chart display — embed the URL in an <img> tag for immediate chart rendering without any client-side drawing.
PDF reports — download the image and insert it into generated kundli reports.
Chat/messaging — send the chart image URL directly in WhatsApp, Telegram, or in-app chat.
North vs South preference — let users choose their regional chart style — both are always returned.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	A required birth field is absent.
400	`INVALID_DATE`	Invalid calendar date.
400	`INVALID_TIME`	Hour/minute/second out of range.
400	`INVALID_TIMEZONE`	Numeric or non-IANA timezone.
400	`INVALID_COORDINATE`	`latitude` / `longitude` out of range.
401	`AUTH_MISSING_KEY`	No API key in request.
401	`AUTH_INVALID_KEY`	Key format invalid or not found.
401	`AUTH_REVOKED_KEY`	Key has been revoked.
403	`AUTH_ORIGIN_DENIED`	Request from non-whitelisted origin.
405	`METHOD_NOT_ALLOWED`	Non-POST request.
429	`RATE_LIMIT_EXCEEDED`	Plan quota exceeded.
500	`CALCULATION_ERROR`	Ephemeris calculation failed.

Error response format

{
  "success": false,
  "error": {
    "code": "INVALID_TIMEZONE",
    "message": "Unrecognised timezone: 'Asia/Calcutta_'. Use a valid IANA identifier such as 'Asia/Kolkata'."
  }
}

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/vedic/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"
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/vedic/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'
    })
  }
);
const result = await response.json();

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

import requests
import os

response = requests.post(
    'https://starsapi.com/api/v3/vedic/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'
    }
)
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',
];

$ch = curl_init('https://starsapi.com/api/v3/vedic/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/vedic/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',
    }),
  );
  return jsonDecode(response.body);
}

import Foundation

func getAscendant() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/vedic/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"
        }
        """.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"
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/vedic/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",
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/vedic/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/vedic/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'
}

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

{
  "status": 200,
  "success": true,
  "data": {
    "chart": {
      "code": "D1",
      "name": "Rashi",
      "images": {
        "north": "https://starsapi.com/api/v3/vedic/charts/d-chart-image.php?key=...&chart=D1&style=north&expires=...&token=...",
        "south": "https://starsapi.com/api/v3/vedic/charts/d-chart-image.php?key=...&chart=D1&style=south&expires=...&token=..."
      }
    }
  },
  "meta": {
    "endpoint": "/api/v3/vedic/natal/chart-image",
    "version": "3.0",
    "response_time_ms": 5,
    "timestamp": "2026-06-09T06:27:15+05:30",
    "credits_remaining": 198594,
    "request_id": "26a42768b3f7afa6",
    "ayanamsa": {
      "name": "Lahiri",
      "value": 23.725957,
      "value_dms": "23°43'33\""
    },
    "node_type": "mean"
  }
}