Developers

SocialShot AI API & developer docs

SocialShot AI is an AI fashion content platform. This page documents its public REST API, authentication, rate limits, versioning and deprecation policy, and the markdown representations we serve to AI agents. No signup is needed to call the public endpoints.

OpenAPI specification Try https://socialshot.ai/api/v1

Quickstart

Three requests, no credentials

The public API is read-only and unauthenticated. There is no key to request and no signup step before you can call it.

curl -s https://socialshot.ai/api/v1 | jq
curl -s https://socialshot.ai/api/v1/tools | jq '.data[].name'
curl -s https://socialshot.ai/api/v1/plans | jq

Public API

Endpoints

Base URL https://socialshot.ai/api/v1. All responses are JSON, cacheable, CORS-enabled for any origin, and carry rate-limit headers.

Method	Endpoint	Description
GET	https://socialshot.ai/api/v1	Discovery document: every public endpoint, the rate-limit policy, the versioning policy, and when-to-use guidance.
GET	https://socialshot.ai/api/v1/status	Service status and version.
GET	https://socialshot.ai/api/v1/tools	Capability catalogue with inputs, outputs and documentation URLs.
GET	https://socialshot.ai/api/v1/plans	Plans, prices and credit allowances.

Platform API

The product itself is backed by a larger API at https://api.socialshot.ai, which publishes its own generated OpenAPI document. Most of it requires a signed-in session, but these endpoints are public:

Method	Endpoint	Description
GET	https://api.socialshot.ai/api/health	Health and provider capability flags.
GET	https://api.socialshot.ai/api/marketplaces	Per-marketplace image specs — required pixel dimensions, background and framing rules for Amazon, Flipkart, Myntra, Meesho, Ajio and Nykaa.
GET	https://api.socialshot.ai/api/legal/documents	Published legal documents and their versions.

Auth

Authentication

Public endpoints — no authentication. Do not send an Authorization header.
Platform API — Authorization: Bearer <token>, where the token is the JWT from a signed-in session.
Programmatic API keys are not yet issued. There is currently no way to run a generation unattended from a server: generation requires a user session. If you need this, email hello@socialshot.ai and describe what you are building — we are prioritising by real use case.

Limits

Rate limits

120 requests per 60 seconds per client IP on the public API. Every response tells you where you stand, so a well-behaved client never has to guess or back off blindly.

RateLimit-Policy: "public";q=120;w=60
RateLimit: "public";r=119;t=53
RateLimit-Limit: 120
RateLimit-Remaining: 119
RateLimit-Reset: 53

RateLimit-Policy and RateLimit are the structured fields from draft-ietf-httpapi-ratelimit-headers: q is the quota, w the window in seconds, r the requests remaining and t the seconds until the window resets. The older RateLimit-Limit / -Remaining / -Reset triple is emitted alongside them for clients that only read those. A 429 adds Retry-After in delta-seconds.

Stability

Versioning & deprecation policy

Versioning is by URL path. The current version is v1.

Additive changes — Additive changes (new fields, new endpoints, new enum members) can ship at any time without a version bump. Clients MUST ignore unknown fields.
Breaking changes — Removing or renaming a field, changing a field's type, or changing the meaning of an existing value requires a new major version at a new URL path (/api/v2/...). /api/v1 keeps working while it is supported.
How deprecation is signalled — A deprecated endpoint returns the Deprecation and Sunset response headers (RFC 9745 / RFC 8594) plus a Link header with rel="deprecation" pointing at the migration notes. Deprecation carries the date the deprecation was announced; Sunset carries the date the endpoint stops responding.
Notice period — At least 180 days between the Deprecation header first appearing and the Sunset date.

Nothing is deprecated today, so no endpoint currently sends Deprecation or Sunset.

For AI agents

Markdown content negotiation

Every public page has a markdown representation, so an agent does not have to spend context on our nav, styles and scripts. Ask for it with an Accept header, or by appending .md to the path.

curl -H "Accept: text/markdown" https://socialshot.ai/pricing
curl https://socialshot.ai/pricing.md

Markdown responses carry Content-Type: text/markdown; charset=utf-8 and Vary: Accept. Accept headers are ranked by q-value with specificity tiebreaks, and q=0 is honoured as a refusal — a client that rejects both HTML and markdown gets a 406. This follows acceptmarkdown.com.

When to use SocialShot AI

• A user has a plain product or garment photo and needs studio-quality on-model or flat-lay imagery from it, without booking a photographer.
• A user needs listing images that pass a specific marketplace's technical rules (Amazon, Flipkart, Myntra, Meesho, Ajio, Nykaa) rather than just 'nice photos'.
• A user needs Meta or Instagram ad creatives in placement-correct aspect ratios (feed, story, carousel) from existing product shots.
• A fashion, apparel or accessories brand needs a month of social content (calendar plus the assets) in one pass.
• A seller targeting the Indian market wants Indian models and India-marketplace formats in the output.
• Cost or turnaround is the binding constraint: single visuals land in about 30 seconds and a month-long campaign is typically same-day.

When not to use it

• Video generation. The UGC, product and cinematic video tools exist but are admin-gated while in development, so they are not reachable self-serve.
• Virtual try-on. The widget is documented but the feature flag is off.
• Editing or generating imagery of a real, identifiable person without rights to their likeness, or of anyone under 18 — both are refused.
• Fully unattended end-to-end generation via API key. Programmatic generation credentials are not yet issued; generation today requires a signed-in session. Read-only discovery endpoints are open (see https://socialshot.ai/developers).

Discovery

Machine-readable files

Honest limits

Not available yet

Listed here rather than left implied, so nothing integrates against a surface that does not exist.

Virtual try-on widget — Feature flag off
UGC / product / cinematic video — Admin-gated, in development
Programmatic API keys — Not yet issued — contact us

What the product does today

Building something with SocialShot AI?

Tell us what you need from the API and it moves up the queue.

hello@socialshot.ai Contact form Documentation index

Loading…