Documentation de l’API de génération

Créer des générations par l’API demande un pack de crédits payant ou un abonnement payant actif, et ne dépense que des crédits payants. Lire, lister et télécharger fonctionnent avec n’importe quelle clé du compte.

Démarrage rapide

Créez une clé sur la page des clés API, gardez-la sur votre serveur et définissez-la comme API_KEY. Les exemples créent une génération avec seed-audio-1.0, la lisent jusqu’à la fin et téléchargent son premier fichier.

Envoyez une nouvelle Idempotency-Key à chaque nouvelle requête. Quand une requête reste sans réponse, renvoyez-la avec la même clé et le même corps : vous obtenez la génération créée par la première requête, facturée une seule fois.

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":"Un phare sur une falaise à l’aube, mer calme, lumière douce."}}'

# 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": "Un phare sur une falaise à l’aube, mer calme, lumière douce."
    }
  },
  { 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>;
}

Clés et permissions

Chaque requête porte Authorization: Bearer avec une clé de la page des clés API. Une clé est sk_ suivi de 43 lettres, chiffres, tirets ou tirets bas, et elle n’est affichée qu’une fois, à sa création ou à son renouvellement. Une requête avec Authorization est jugée sur sa seule clé, jamais sur une session connectée à côté.

Une clé est soit en lecture seule (elle liste, lit et télécharge), soit autorisée à générer (elle crée et annule). Une clé en lecture seule reçoit 403 insufficient_scope quand elle tente de créer ou d’annuler, et rien n’est écrit.

Une clé peut avoir une liste d’adresses IP et de réseaux autorisés : depuis toute autre adresse, elle reçoit 403 ip_not_allowed. Donner plus de permissions à une clé, relever une limite ou élargir sa liste demande une connexion récente ; les restreindre, jamais.

Renouveler une clé lui donne aussitôt une nouvelle valeur et l’ancienne cesse de fonctionner. Révoquer une clé l’arrête pour de bon : ses générations pas encore envoyées à un modèle sont annulées et leurs crédits rendus, et celles déjà en cours se terminent.

Seuls les comptes avec un accès payant créent des générations par l’API (403 not_eligible sinon), et l’API ne dépense que des crédits payants (402 insufficient_credits). Les crédits offerts et de connexion restent pour le site.

Points d’accès de l’API de génération

Tous les chemins sont sur ce site. Les corps des requêtes et des réponses sont en JSON, sauf les fichiers de résultat.

https://demo.freshapp.ai

Modèles et prix

Les modèles activés sur ce site, tels que l’API les accepte : mettez l’identifiant dans model et les champs dans input. Une requête réserve son résultat le plus cher à sa création ; à la fin, vous payez ce qui a été livré.

Idempotence

Créer une génération demande un en-tête Idempotency-Key de 1 à 128 lettres, chiffres, points, deux-points, tirets bas ou tirets. Utilisez un identifiant de votre propre système, comme un numéro de commande, pour qu’un même travail ait toujours la même clé.

La même clé avec la même requête renvoie la même génération, quel que soit le nombre d’envois, et elle n’est facturée qu’une fois. La même clé avec une autre requête donne 409 idempotency_conflict, et rien n’est créé.

Un délai dépassé ou une connexion coupée ne signifie pas que la requête a échoué. Renvoyez-la avec la même clé et le même corps, et gardez les deux jusqu’à obtenir une réponse. Un 5xx, un 429 ou un 408 se traite de la même façon : attendez ce que dit Retry-After, puis renvoyez la requête telle quelle.

Statuts et suivi

Lisez une génération avec GET /api/v1/generations/{id} toutes les 5 secondes au début, puis jusqu’à toutes les 10 secondes, jusqu’à ce que son statut soit final. Un 429 indique dans Retry-After quand relire.

billing.reserved_credits est ce que la création a réservé. Une fois la génération réglée, charged_credits est ce que vous avez payé et refunded_credits ce qui est revenu ; d’ici là, les deux valent null et held_credits indique ce qui est réservé.

Une génération qui attend une vérification manuelle affiche review avec l’heure du début de la vérification, et garde ses crédits jusqu’à la fin de celle-ci ; ensuite, elle continue ou ses crédits reviennent.

Fichiers de résultat

Chaque sortie livrée a une url sur ce site. Pour une clé, c’est un lien signé valable une heure sans la clé et depuis n’importe quelle adresse : vous pouvez le confier à un outil de téléchargement. Après une heure, relisez la génération pour obtenir un nouveau lien.

Avec la clé elle-même, GET /api/media/{id} renvoie aussi le fichier, dans les limites de la liste d’adresses de la clé. Les deux acceptent HEAD et une plage d’octets (Range: bytes=0-1023), et ne redirigent jamais vers un autre site.

Un fichier cité dans une entrée, comme un extrait audio ou une image, doit avoir été envoyé par ce compte sur le site, faire partie des exemples du site, ou être un lien vers une source que le site autorise ; tout le reste est refusé avant toute réservation de crédits.

Limites

Chaque limite ci-dessous est celle que ce site applique aujourd’hui, et chaque refus indique laquelle a été atteinte.

• Une requête réserve au plus 150 crédits, la requête la plus chère des modèles activés. Une clé peut avoir une limite plus basse, et le max_credits d’une requête l’abaisse pour cette requête ; au-delà, la réponse est 400 request_limit_exceeded.
• Chaque clé dépense au plus 5 000 crédits par jour UTC, sauf si vous lui fixez sa propre limite, jusqu’à 1 000 000 ; au-delà, la clé reçoit 429 key_daily_limit_exceeded jusqu’au jour UTC suivant.
• Toutes les clés d’un compte, avec ses clients d’IA, dépensent au plus 10 000 crédits par jour UTC, sauf si vous fixez la limite du compte ; au-delà, la réponse est 429 account_daily_limit_exceeded.
• Chaque clé et chaque compte envoie au plus 20 créations et annulations et 240 lectures et téléchargements par minute ; au-delà, 429 rate_limited avec Retry-After.
• Au plus 2 générations d’un compte tournent en même temps ; une autre attend avec 429 too_many_active.
• Un corps de requête fait au plus 32 Kio de JSON ; plus grand, il donne 413 request_too_large.

Codes d’erreur

Une erreur a la forme {"error": {"code": …, "message": …}}. Le code est toujours l’un de ceux-ci, et le message est en anglais, pour les développeurs. Un 429 ou un 503 indique dans Retry-After combien de secondes attendre. Une génération échouée ou annulée porte dans son champ error l’un des codes marqués comme ceux d’une génération.

Client TypeScript et hook React

Le client TypeScript, open-api-client.ts, n’a besoin d’aucun autre paquet et tourne sur les serveurs, dans les workers et dans les navigateurs. Sur un serveur, donnez-lui baseUrl et apiKey ; dans un navigateur sur ce site, ne lui donnez ni l’un ni l’autre, et les requêtes utilisent la session du visiteur.

create envoie une Idempotency-Key, la vôtre ou une nouvelle valeur aléatoire, et renvoie la même requête après une connexion coupée, un 5xx, un 429 ou un 408, en attendant ce que dit Retry-After. Quand il abandonne, son erreur porte la clé, pour renvoyer la requête plus tard. Avec un store comme localStorage, une requête garde sa première clé après un rechargement de la page.

wait lit une génération jusqu’à sa fin, toutes les 5 secondes au début puis jusqu’à 10, et s’arrête quand vous l’interrompez. download récupère le fichier d’une sortie et n’envoie la clé qu’aux liens non signés de ce site.

Le hook React, open-api-react.ts, suit une génération avec le wait du client et s’arrête quand le composant est démonté. Téléchargez les deux fichiers, placez-les côte à côte et renommez-les en .ts.

Téléchargements