A binary endpoint with JSON errors
/v1/silks/{id}Included with active API accessA generated RacingAPI.net racing-colour PNG for one horse in one race.
{id} is the horse ID (1 to 12 digits). raceId is required and must be the race that horse is declared in, from the same region and day. Add date or tomorrow=true when you are not on today's feed. Each runner and finisher also carries a ready-made silkUrl: a relative, authenticated path for exactly this horse, race and date, which you can append to the base URL on your server.
Success is image/png bytes. Failure is the standard JSON error body. A runner with no generated silk ready returns 404 silk_not_found; we never substitute an invented image, so show a neutral placeholder. Silks are racing colours, not portraits, and need no separate approval.
Proxy pattern: your route, your cache
- 1<img src=/silks/HORSE?race=RACE>. The page points at your own route. No key in the URL.
- 2Your image route. Validates both IDs as digits, then checks a disk or memory cache.
- 3/v1/silks/{id}?raceId=. Called on a cache miss with X-API-Key.
- 4Cache and stream. Store the PNG and send it with a long Cache-Control.
// Express-style handler: GET /silks/:horseId?race=RACE_ID&date=YYYY-MM-DD
const cache = new Map(); // swap for disk or object storage in production
export async function silkRoute(req, res) {
const horseId = String(req.params.horseId);
const raceId = String(req.query.race || "");
const date = req.query.date ? String(req.query.date)
: new Date().toLocaleDateString("en-CA", { timeZone: "Europe/London" });
if (!/^\d{1,12}$/.test(horseId) || !/^\d{1,12}$/.test(raceId)) return res.status(400).end();
if (date && !/^\d{4}-\d{2}-\d{2}$/.test(date)) return res.status(400).end();
const key = horseId + ":" + raceId + ":" + date;
const saved = cache.get(key);
let png = saved && saved.expires > Date.now() ? saved.png : null;
if (!png) {
const url = new URL("/v1/silks/" + horseId, "https://racingapi.net");
url.searchParams.set("region", "uk");
url.searchParams.set("raceId", raceId);
if (date) url.searchParams.set("date", date);
const upstream = await fetch(url, { headers: { "X-API-Key": process.env.RACINGAPI_KEY } });
if (upstream.status === 404) return res.status(404).end(); // show your placeholder
if (!upstream.ok) return res.status(502).end();
png = Buffer.from(await upstream.arrayBuffer());
if (cache.size >= 2000) cache.delete(cache.keys().next().value);
cache.set(key, { png, expires: Date.now() + 86_400_000 });
}
res.set("Content-Type", "image/png");
res.set("Cache-Control", "public, max-age=86400");
res.send(png);
}Caching and fair use
- Silk requests count like any other request. Caching on your side is what keeps a 400-runner card affordable.
- Successful PNGs can be reused from the gateway cache for up to 24 hours. Repeated requests consume allowance and do not force image regeneration.
- Never build an image URL that includes your key. Never hand
silkUrlstraight to a browser; it needs authentication. - Silks support your own racing displays. Do not publish them as a standalone image library.
See the API reference for the silk error codes.
Reference material
Exact schemas: API reference. First call: Quickstart. Copy-ready helpers: Code examples. Plans: Pricing.