# Overview

Source: https://docs.foodshot.ai/overview

> What the API does, how a job runs, your keys and the basics.

The FoodShot Partner API is for marketplaces, delivery apps and online menus: you send a photo of a dish and a style, and get back a finished food photo for your listing.

## How it works

1. Call `POST /v1/generations` with the photo, a `style_id` and an `Idempotency-Key`. You get a generation id back, usually within seconds.
2. A `generation.succeeded` webhook tells you when the image is ready, or you poll `GET /v1/generations/{id}`. Our objective is about 30-40 seconds once a job starts.
3. Download `output.url` from your server and keep your own copy. The link works for 24 hours.

If a job fails, its credit is refunded automatically.

## Keys

Send your key as a Bearer token in the `Authorization` header:

```bash
curl https://api.foodshot.ai/v1/account \
  -H "Authorization: Bearer $FOODSHOT_API_KEY"
```

|                 | Test                        | Live                          |
| --------------- | --------------------------- | ----------------------------- |
| Key starts with | `fs_test_`                  | `fs_live_`                    |
| Results         | Sample images marked SAMPLE | Real results from your photos |
| Credits         | Never used                  | 1 per finished image          |

* A new key is shown once in the dashboard: store it in a secret manager or an environment variable.
* Live keys work only from your server: a browser gets `403 permission_denied`.
* Each key sees only its own environment.
* Keys don't expire: to replace one, create a new key, deploy it, then revoke the old one.

Build with a test key, then switch to a live key. See [Testing and going live](https://docs.foodshot.ai/guides/testing).

## Basics

* **Base URL:** `https://api.foodshot.ai`. Every path starts with `/v1`.
* **Format:** JSON in and out, `snake_case` names, UTC timestamps.
* **Help:** every response has a `FoodShot-Request-Id` header. Send it to us when you ask for help.

## Endpoints

| Endpoint                                                | What it does                                                   |
| ------------------------------------------------------- | -------------------------------------------------------------- |
| [`POST /v1/generations`](https://docs.foodshot.ai/reference/create-generation)  | Create a generation from a photo                               |
| [`GET /v1/generations/{id}`](https://docs.foodshot.ai/reference/get-generation) | Get a generation and its result                                |
| [`GET /v1/generations`](https://docs.foodshot.ai/reference/list-generations)    | List your generations                                          |
| [`GET /v1/styles`](https://docs.foodshot.ai/reference/list-styles)              | List the styles                                                |
| [`GET /v1/account`](https://docs.foodshot.ai/reference/get-account)             | Credits, limits and usage                                      |
| `GET /v1/health`                                        | `200` when the API is healthy, `503` otherwise. No key needed. |

Every field is in the API reference, made from our [OpenAPI file](https://docs.foodshot.ai/openapi-v1.yaml).

## About the results

* Marked as AI-generated. Results carry an invisible AI watermark and an AI label in their metadata.
* Review before you publish. Styles are made to keep the dish unchanged, but small details can differ.
* Yours to use. You and your vendors may use results commercially. See the [API Terms](https://docs.foodshot.ai/policies/terms).