Media & drawings

The kinds of asset

Five kinds, one shape. GET /v1/firearms/{id}/media lists everything a firearm has as one array, each item tagged with its kind, and /media/{selector} fetches one by that kind without a prior lookup.

Silhouettes

2,589 firearms have a line-art silhouette. These four are the exact files the website renders, loaded from this page's own bundle; on the dark theme they are inverted, as the website inverts them.

• ak-47
• barrett-m82a1
• glock-17-gen5
• remington-870

All 2,589 silhouettes in the gallery

1. 1A reference photograph is normalised: flattened, converted to sRGB, resized. Photographs that fail moderation fall back to a text-only generation and are marked as such.
2. 2An image model draws bold black-on-white line art of the subject alone, no background. A prompt that asks for a filled silhouette gives a blob; the pipeline asks for line art and fills it afterwards.
3. 3The result is cleaned in one pass: background to transparent, tight crop, anti-alias halo mapped to alpha so no light ring survives on a dark page.
4. 4The bitmap is traced to vector paths with VTracer at zero dilation, so lines keep their drawn weight. The output is a solid-fill SVG, not a stroke outline.
5. 5The file is recorded on the firearm as svgLineArtUrl, uploaded to the asset CDN, and served through the API with the stroke colour and width you ask for.

On the website the same file is served obfuscated and decoded client-side, which is why an API caller receives an absolute CDN URL instead: a path no consumer could fetch was documented for a while as if they could. The field is in the field reference.

Cartridge illustrations

A cartridge is never drawn from its name. It is drawn from up to 16 fields on the caliber record: rim, base, shoulder and neck diameters, case and overall length, bullet length and diameter, head type, case shape, material, projectile kind, bullet profile, closure and marking colour. The six below are drawn on this page by the shared renderer from the record as it stands.

• 9x19mm Parabellum14 of 16 drawing fields on the record95% confidenceheadrimlesscasetaperedprojectilebulletprofileround_noseclosurebullet
• .45 ACP14 of 16 drawing fields on the record95% confidenceheadrimlesscasestraightprojectilebulletprofileround_noseclosurebullet
• .223 Remington15 of 16 drawing fields on the record95% confidenceheadrimlesscasebottleneckprojectilebulletprofilespitzerclosurebullet
• 7.62x39mm15 of 16 drawing fields on the record95% confidenceheadrimlesscasebottleneckprojectilebulletprofilespitzerclosurebullet
• 12 Gauge12 of 16 drawing fields on the record70% confidenceheadrimmedcasestraightprojectileshotclosurefold_crimp
• .50 BMG15 of 16 drawing fields on the record90% confidenceheadrimlesscasebottleneckprojectilebulletprofilespitzerclosurebullet

1. 1resolveCartridgeGeometry turns the record into drawable millimetres. Every figure the record carries is used as-is; a missing one is filled from ratio heuristics field by field, and the geometry says which were guessed.
2. 2The case outline is built from head type and case shape, the projectile from profile and kind, then crimps, wads or pellets from the closure. projectile_kind: none is a blank and draws as one.
3. 3Materials become gradients: brass is brass, lacquered steel is lacquered steel, a paper hull is paper. The marking colour is painted where the record says it belongs.
4. 4Both renderers, the inline glyph and the measured chart, draw from the same geometry, so a caliber cannot look different on two pages.

The closed vocabularies a cartridge is drawn from

caseShapeCase profile: straight, bottleneck, tapered, belted.

straight, tapered, bottleneck, none

caseMaterialWhat the case is made of: brass, steel, aluminium, polymer.

brass, nickel_brass, steel, lacquered_steel, aluminium, polymer, paper, caseless, none

projectileKindnone is a blank.

bullet, none, shot, slug, round_ball, flechette, dart, pellet, rocket, grenade, signal

bulletProfileBullet shape: fmj, hollow_point, soft_point, spitzer, round_nose.

spitzer, spitzer_boat_tail, round_nose, flat_nose, wadcutter, semi_wadcutter, hollow_point, truncated_cone, round_ball

closureWhat seals the case mouth; a blank is a star crimp.

bullet, star_crimp, rosette_crimp, roll_crimp, fold_crimp, wad, paper, none

markingColorPaint that identifies the load: crimp lacquer on a blank, tip colour on a military round.

black, white, red, orange, yellow, green, blue, purple, pink, brown, grey, silver, gold

The figures come from the maker's or a standards body's published drawing and carry a confidence score like any record. Every cartridge is in the calibers reference with all of these fields.

Bullet diagrams

A load's bullet_type is classified into one of 8 profiles and drawn as a side cross-section scaled to the caliber's bullet diameter. The API renders it on request at /v1/ammunition/{id}/bullet.svg; the rows below are that renderer's output for each profile at two diameters.

1# Public: no key needed2curl https://api.gunspec.io/v1/ammunition/m882/bullet.svg3 4# Or straight into an img tag5<img src="https://api.gunspec.io/v1/ammunition/m882/bullet.svg" alt="M882 Ball, side profile">

Rifle diameters get a longer body and a sharper ogive than pistol ones, so the same profile reads correctly across calibers. The endpoint needs no key. Every load in the ammunition reference carries its diagram URL as bulletSvgUrl.

Photographs, schematics and models

The assets we host or link rather than draw. Each comes with the credit it needs to be reused.

• Photographs and renders are indexed by GET /v1/firearms/media, a three-field row per firearm built for media grids and mirrors, with a fingerprint that changes when imagery is added or removed.
• Schematics are exploded views and technical drawings from manufacturer and archival material, on Studio and above; the access matrix has the full gating.
• 3D models are glTF binaries with meshopt compression, WebP textures and quantised meshes. A loader needs those three standard extensions and nothing else.
• Assets we link rather than host answer with a 302 to their location; assets in our own bucket stream from the endpoint. Either way url on a media item is absolute and fetchable.

Fetching media

One resource for everything, plus the older per-kind routes, which remain. Addressing by kind needs no prior lookup; format=json returns the metadata without moving bytes, format=datauri inlines up to 256 KB.

1# Everything a firearm has, one shape, with a credit block per item2curl -H "X-API-Key: your_api_key" \3  https://api.gunspec.io/v1/firearms/ak-47/media4 5# The silhouette as SVG, stroke recoloured, no prior lookup6curl -H "X-API-Key: your_api_key" \7  "https://api.gunspec.io/v1/firearms/ak-47/media/silhouette?stroke_color=%23ffffff"8 9# Just the metadata, no bytes10curl -H "X-API-Key: your_api_key" \11  "https://api.gunspec.io/v1/firearms/ak-47/media/photo?format=json"

Every media response carries an ETag and answers 304 when unchanged, so a mirror re-fetches nothing that did not move; see caching. A firearm gaining or losing an asset fires firearm.updated to webhook subscribers.

Reuse and safety

Every media item carries the attribution needed to reuse it, and every SVG the API serves is sandboxed before it reaches a browser.

The credit block on every item

credit.source

Where the record came from: a curated entry, an inference, or an import.

credit.author

Who made the asset, where it is credited.

credit.sourceUrl

Page the asset or document was taken from.

credit.license

Licence the asset is held under, where one is recorded.

How SVGs are served

An SVG can carry script. Every one the API serves, including silhouettes, bullet drawings and media, is sent with a Content-Security-Policy that stops it running anything if opened directly, and colour values written into a silhouette are validated and escaped. The policy, from the data protections page:

default-src

'none'

style-src

'unsafe-inline'

img-src

data:

sandbox

Press kit and the certification sealMedia fields in the field reference