Documentación de la API de generación

Crear generaciones por la API requiere un paquete de créditos de pago o una suscripción de pago activa, y solo gasta créditos de pago. Consultar, listar y descargar funcionan con cualquier clave de la cuenta.

Inicio rápido

Crea una clave en la página de claves de API, guárdala en tu servidor y asígnala a API_KEY. Los ejemplos crean una generación con seed-audio-1.0, la consultan hasta que termina y descargan su primer archivo.

Envía una Idempotency-Key nueva con cada solicitud nueva. Cuando una solicitud no recibe respuesta, vuelve a enviarla con la misma clave y el mismo cuerpo: recibes la generación que creó la primera solicitud y se cobra una sola vez.

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 faro sobre un acantilado al amanecer, mar en calma, luz suave."}}'

# 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 faro sobre un acantilado al amanecer, mar en calma, luz suave."
    }
  },
  { 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>;
}

Claves y permisos

Cada solicitud lleva Authorization: Bearer con una clave de la página de claves de API. Una clave es sk_ seguido de 43 letras, dígitos, guiones o guiones bajos, y se muestra una sola vez, al crearla o rotarla. Una solicitud con Authorization se juzga solo por su clave, nunca por una sesión iniciada a su lado.

Una clave solo lee (lista, consulta y descarga) o también puede generar (crea y cancela). Una clave de solo lectura recibe 403 insufficient_scope cuando intenta crear o cancelar, y no se escribe nada.

Una clave puede tener una lista de IP permitidas con direcciones y redes: desde cualquier otra dirección recibe 403 ip_not_allowed. Dar más permisos a una clave, subir un límite o ampliar la lista requiere un inicio de sesión reciente; restringirlos, nunca.

Rotar una clave le da un valor nuevo al instante y el anterior deja de funcionar. Revocarla la detiene para siempre: sus generaciones aún no enviadas a un modelo se cancelan y sus créditos vuelven, y las que ya están en curso terminan.

Solo las cuentas con acceso de pago crean generaciones por la API (si no, 403 not_eligible), y la API solo gasta créditos de pago (402 insufficient_credits). Los créditos de regalo y de registro diario quedan para el sitio web.

Endpoints de la API de generación

Todas las rutas están en este sitio. Los cuerpos de solicitud y respuesta son JSON, salvo los archivos de resultado.

https://demo.freshapp.ai

Modelos y precios

Los modelos activados en este sitio, como los acepta la API: usa el id como model y los campos como input. Una solicitud reserva su resultado más caro al crearse; cuando termina, pagas lo que se entregó.

Idempotencia

Crear una generación requiere una cabecera Idempotency-Key de 1 a 128 letras, dígitos, puntos, dos puntos, guiones bajos o guiones. Usa un id de tu propio sistema, como un número de pedido, para que el mismo trabajo siempre tenga la misma clave.

La misma clave con la misma solicitud devuelve la misma generación, por muchas veces que se envíe, y se cobra una sola vez. La misma clave con otra solicitud da 409 idempotency_conflict y no se crea nada.

Un tiempo de espera agotado o una conexión cortada no significan que la solicitud falló. Vuelve a enviarla con la misma clave y el mismo cuerpo, y guarda ambos hasta tener respuesta. Un 5xx, un 429 o un 408 se tratan igual: espera lo que diga Retry-After y vuelve a enviar la solicitud sin cambios.

Estados y consultas

Consulta una generación con GET /api/v1/generations/{id} cada 5 segundos al principio y luego hasta cada 10 segundos, hasta que su estado sea final. Un 429 indica en Retry-After cuándo volver a consultar.

billing.reserved_credits es lo que reservó la creación. Una vez liquidada, charged_credits es lo que pagaste y refunded_credits lo que volvió; hasta entonces ambos son null y held_credits muestra lo reservado.

Una generación que espera una revisión manual muestra review con la hora en que empezó la revisión, y conserva sus créditos hasta que termina; después continúa o sus créditos vuelven.

Archivos de resultado

Cada salida entregada tiene una url en este sitio. Para una clave, es un enlace firmado que funciona durante una hora sin la clave y desde cualquier dirección, así que puedes dárselo a una herramienta de descarga. Pasada la hora, vuelve a consultar la generación para obtener un enlace nuevo.

Con la propia clave, GET /api/media/{id} también devuelve el archivo, dentro de la lista de IP de la clave. Ambos aceptan HEAD y un rango de bytes (Range: bytes=0-1023), y nunca redirigen a otro sitio.

Un archivo citado en una entrada, como una muestra de audio o una imagen, debe haberlo subido esta cuenta al sitio web, ser una de las muestras del sitio o un enlace a una fuente que el sitio permite; cualquier otra cosa se rechaza antes de reservar créditos.

Límites

Cada límite de abajo es el que este sitio aplica ahora, y cada rechazo indica cuál se alcanzó.

• Una solicitud reserva como máximo 150 créditos, la solicitud más cara de los modelos activados. Una clave puede tener un límite menor, y el max_credits de una solicitud lo baja para esa solicitud; por encima, la respuesta es 400 request_limit_exceeded.
• Cada clave gasta como máximo 5000 créditos por día UTC salvo que le fijes su propio límite, hasta 1.000.000; al superarlo, la clave recibe 429 key_daily_limit_exceeded hasta el siguiente día UTC.
• Todas las claves de una cuenta, con sus clientes de IA, gastan como máximo 10.000 créditos por día UTC salvo que fijes el límite propio de la cuenta; al superarlo, la respuesta es 429 account_daily_limit_exceeded.
• Cada clave y cada cuenta envía como máximo 20 creaciones y cancelaciones y 240 consultas y descargas por minuto; al superarlo, 429 rate_limited con Retry-After.
• Como máximo 2 generaciones de una cuenta se ejecutan a la vez; otra espera con 429 too_many_active.
• El cuerpo de una solicitud tiene como máximo 32 KiB de JSON; uno mayor da 413 request_too_large.

Códigos de error

Un error tiene la forma {"error": {"code": …, "message": …}}. El código siempre es uno de estos, y el mensaje está en inglés, para desarrolladores. Un 429 o un 503 indica en Retry-After cuántos segundos esperar. Una generación fallida o cancelada lleva en su campo error uno de los códigos marcados como de una generación.

Cliente TypeScript y hook de React

El cliente TypeScript, open-api-client.ts, no necesita ningún otro paquete y funciona en servidores, workers y navegadores. En un servidor, pásale baseUrl y apiKey; en un navegador de este sitio, no le pases ninguno, y las solicitudes usan la sesión del propio visitante.

create envía una Idempotency-Key, la tuya o un valor aleatorio nuevo, y vuelve a enviar la misma solicitud tras una conexión cortada, un 5xx, un 429 o un 408, esperando lo que diga Retry-After. Cuando se rinde, su error lleva la clave, para que reenvíes la solicitud más tarde. Con un store como localStorage, una solicitud conserva su primera clave al recargar la página.

wait consulta una generación hasta que termina, cada 5 segundos al principio y luego hasta 10, y se detiene cuando lo cancelas. download obtiene el archivo de una salida y solo envía la clave a los enlaces sin firmar de este sitio.

El hook de React, open-api-react.ts, sigue una generación con el wait del cliente y se detiene cuando el componente se desmonta. Descarga ambos archivos, ponlos juntos y cámbiales la extensión a .ts.

Descargas