Generation API documentation

Creating generations through the API needs a paid credit pack or an active paid subscription, and spends paid credits only. Reading, listing and downloading work for any key of the account.

Quick start

Create an API key on the API keys page, keep it on your server, and set it as API_KEY. The examples create a generation with seed-audio-1.0, read it until it ends, and download its first file.

Send a new Idempotency-Key with each new request. When a request gets no answer, send it again with the same key and the same body: you get the generation the first request made, and you are charged once.

export API_ORIGIN='https://demo.freshapp.ai'
export API_KEY='sk_YOUR_API_KEY'

curl --fail-with-body "$API_ORIGIN/api/v1/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1001' \
  -d '{"model":"seed-audio-1.0","input":{"prompt":"A lighthouse on a cliff at dawn, calm sea, soft light."}}'

# Read it every 5 to 10 seconds until its status ends.
curl --fail-with-body "$API_ORIGIN/api/v1/generations/GENERATION_ID" \
  -H "Authorization: Bearer $API_KEY"

# A delivered output's url is a signed link: no key needed.
curl --fail-with-body -o result "OUTPUT_URL"

import { createClient } from './open-api-client';

const client = createClient({
  baseUrl: "https://demo.freshapp.ai",
  apiKey: process.env.API_KEY, // on your server only
});
const generation = await client.create(
  {
    "model": "seed-audio-1.0",
    "input": {
      "prompt": "A lighthouse on a cliff at dawn, calm sea, soft light."
    }
  },
  { idempotencyKey: "order-1001" }
);
const done = await client.wait(generation.id);
for (const output of done.outputs)
  if (output.status === 'delivered') {
    const file = await client.download(output);
    // file.body is the output, as output.content_type says
  }

import { createClient } from './open-api-client';
import { useGeneration } from './open-api-react';

// In a browser on this site: no key, the visitor's own session.
const client = createClient();

export function Progress({ id }: { id: string }) {
  const { generation, error, done } = useGeneration(client, id);
  if (error) return <p>{String(error)}</p>;
  return <p>{generation?.status ?? '…'}{done ? ' ✓' : ''}</p>;
}

Keys and permissions

Every request carries Authorization: Bearer with a key from the API keys page. A key is sk_ followed by 43 letters, digits, hyphens or underscores, and it is shown once, when it is created or rotated. A request with Authorization is judged by its key alone, never by a signed-in session beside it.

A key either only reads (it lists, reads and downloads) or may also generate (it creates and cancels). A key that only reads gets 403 insufficient_scope when it tries to create or cancel, and nothing is written.

A key may carry an IP allowlist of addresses and networks: from any other address it gets 403 ip_not_allowed. Giving a key more permission, raising a limit or widening an allowlist needs a recent sign-in; narrowing never does.

Rotating a key gives it a new value at once and the old value stops. Revoking a key stops it for good: its generations not yet sent to a model are canceled and their credits returned, and generations already under way still finish.

Only accounts with paid access create generations through the API (403 not_eligible otherwise), and the API spends paid credits only (402 insufficient_credits). Gift and check-in credits stay for the website.

Generation API endpoints

All paths are on this site. Request and response bodies are JSON, except the result files.

https://demo.freshapp.ai

Models and prices

The models enabled on this site, as the API takes them: use the id as model, and the fields as input. A request reserves its most expensive outcome when it is created; when it ends, you pay for what was delivered.

Idempotency

Creating a generation needs an Idempotency-Key header of 1 to 128 letters, digits, dots, colons, underscores or hyphens. Use an id from your own system, such as an order number, so that the same piece of work always gets the same key.

The same key with the same request returns the same generation, however often it is sent, and it is charged once. The same key with a different request is 409 idempotency_conflict, and nothing is created.

A timeout or a broken connection does not mean the request failed. Send it again with the same key and the same body, and keep both until you have an answer. A 5xx, a 429 or a 408 is answered the same way: wait as Retry-After says, then send the request again unchanged.

Statuses and polling

Read a generation with GET /api/v1/generations/{id} every 5 seconds at first and then up to every 10 seconds, until its status ends. A 429 says in Retry-After when to read again.

billing.reserved_credits is what creating the generation held. Once it settles, charged_credits is what you paid and refunded_credits what came back; until then both are null and held_credits shows what is held.

A generation that waits for a manual check shows review with the time the check began, and it keeps its credits until the check ends; then it continues or its credits come back.

Result files

Each delivered output has a url on this site. For a key, it is a signed link that works for an hour without the key and from any address, so you can hand it to a download tool. After an hour, read the generation again for a fresh link.

With the key itself, GET /api/media/{id} returns the file too, within the key's allowlist. Both answer HEAD and one byte range (Range: bytes=0-1023), and never redirect to another site.

A file referenced in an input, such as an audio sample or an image, must be one this account uploaded on the website, one of the site's own samples, or a link from a source the site allows; anything else is refused before credits are held.

Limits

Every limit below is the one this site enforces now, and every refusal says which one was reached.

• One request reserves at most 150 credits, the most expensive request of the enabled models. A key may be set lower, and a request's max_credits lowers it for that request; over it the answer is 400 request_limit_exceeded.
• Each key spends at most 5,000 credits a UTC day unless you set its own limit, up to 1,000,000; past it, the key gets 429 key_daily_limit_exceeded until the next UTC day.
• All keys of an account, with its AI clients, spend at most 10,000 credits a UTC day unless you set the account's own limit; past it, the answer is 429 account_daily_limit_exceeded.
• Each key and each account sends at most 20 creates and cancels and 240 reads and downloads a minute; past it, 429 rate_limited with Retry-After.
• At most 2 generations of an account run at once; another one waits with 429 too_many_active.
• A request body is at most 32 KiB of JSON; a larger one is 413 request_too_large.

Error codes

An error is {"error": {"code": …, "message": …}}. The code is always one of these, and the message is English for developers. A 429 or a 503 says in Retry-After how many seconds to wait. A generation that failed or was canceled carries one of the codes marked as a generation's in its error field.

TypeScript client and React hook

The TypeScript client, open-api-client.ts, needs no other package and runs on servers, in workers and in browsers. On a server, give it baseUrl and apiKey; in a browser on this site, give it neither, and requests use the visitor's own session.

create sends an Idempotency-Key, yours or a new random one, and sends the same request again after a broken connection, a 5xx, a 429 or a 408, waiting as Retry-After says. When it gives up, its error carries the key, so you can send the request again later. With a store such as localStorage, a request keeps its first key across a page reload.

wait reads a generation until it ends, 5 seconds apart at first and then up to 10, and stops when you abort it. download fetches an output's file, and sends the key only to this site's own unsigned links.

The React hook, open-api-react.ts, follows one generation with the client's wait and stops when the component unmounts. Download both files, keep them side by side and rename them to .ts.

Downloads