HungryShot API for developers

The OpenAPI 3.1 document is published at /openapi.json (JSON) and /openapi.yaml (YAML). Every operation has a unique operationId, a description, typed parameters and response schemas. Interactive reference: /api-docs.

Create an API key in Studio > Settings > API Keys and send it as a bearer token: Authorization: Bearer psl_live_<key>. Keys only work while the owning account is on the Expert Pro plan.

Base URL: https://hungryshot.com/api/v1

• GET /me (getMe): plan and key metadata.
• GET /credits (getCredits): remaining credit balance.
• GET /tools (listTools): tools, sync/async mode and credit cost.
• GET /catalog (getCatalog): stable ids for dish categories, camera angles, surfaces, people and motions.
• POST /ad-crafter (createAdCrafterListing): synchronous; dish photo in, dish name, menu description, captions, hashtags, allergen note and styled image out.
• GET /ad-crafter/options (getAdCrafterOptions): destinations with copy limits, languages, tones, dietary tags.
• POST /beautifier (createBeautifierImage): synchronous; phone photo of a dish to a studio-quality food photo.
• POST /recoloration (createRecoloration): synchronous; recolor tableware, packaging, cups or drinks to a brand colour.
• POST /photoshoots (createPhotoshoot): asynchronous; styled food shoot, returns 202 and a job_id.
• POST /video (createVideo): asynchronous; dish clip with a motion, returns 202 and a job_id.
• GET /video/motions (listVideoMotions): the 16 food motions with default prompts.
• POST /models (createModel): asynchronous; generate a chef, server, diner or hands, returns 202 and a job_id.
• GET /models (listPeople): saved people.
• GET /jobs (listJobs): recent async jobs.
• GET /jobs/{id} (getJob): poll an asynchronous job until status is completed or failed.

Every response, including errors and unknown /api paths, is JSON in the shape {"data": ..., "error": ...}. An error carries a machine-readable code (invalid_request, unauthorized, insufficient_credits, forbidden, not_found, rate_limited, internal_error, upstream_error), a message, and a hint that says how to resolve it.

Each key is limited to 60 requests per minute by default. Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy headers; a 429 response also carries Retry-After (seconds).

The major version is in the URL (/api/v1) and echoed in the API-Version response header. Within v1 we only add optional fields and endpoints. A deprecated endpoint answers with a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) at least 6 months before removal. No endpoint is deprecated today; the Ad Crafter listing_* response aliases are deprecated fields kept for one release.

HungryShot CLI (npm package foodyshot-cli) wraps the API for scripts and agents: npx foodyshot-cli credits, npx foodyshot-cli job <id>, or pipe a JSON body into npx foodyshot-cli post beautifier. Set FOODYSHOT_API_KEY to your API key.

curl https://hungryshot.com/api/v1/credits \
  -H "Authorization: Bearer psl_live_<your_key>"

# 200 OK
# RateLimit-Limit: 60
# RateLimit-Remaining: 59
# RateLimit-Reset: 42
# {"data":{"credits_remaining":420},"error":null}