生成 API 文档

通过 API 创建生成任务需要买过付费积分包或有有效的付费订阅，而且只扣付费积分。账号的任何密钥都可以查询、列出和下载。

快速开始

在 API 密钥页创建一把密钥，只放在你的服务器上，并设成 API_KEY。下面的示例用 seed-audio-1.0 创建一个生成任务，查询到它结束，再下载第一个文件。

每个新请求发送一个新的 Idempotency-Key。请求没有收到回复时，用同一个键和同样的请求体再发一次：你拿到的是第一次请求创建的任务，只扣一次费。

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":"黎明时分悬崖上的灯塔，海面平静，光线柔和。"}}'

# 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": "黎明时分悬崖上的灯塔，海面平静，光线柔和。"
    }
  },
  { 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>;
}

密钥和权限

每个请求都在 Authorization: Bearer 里带上 API 密钥页创建的密钥。密钥是 sk_ 加 43 个字母、数字、连字符或下划线，只在创建和轮换时显示一次。带了 Authorization 的请求只按这把密钥判断，不会改用旁边的登录状态。

密钥要么只读（查列表、查任务、下载），要么还能生成（创建和取消）。只读密钥尝试创建或取消时得到 403 insufficient_scope，什么都不会写入。

密钥可以带一个由地址和网段组成的 IP 白名单：从其他地址发来的请求得到 403 ip_not_allowed。给密钥更多权限、调高上限或放宽白名单需要最近重新登录过；收紧则不需要。

轮换密钥会立刻生成新值，旧值马上失效。作废密钥后它永久失效：还没提交给模型的任务会被取消并退回积分，已经在运行的任务照常完成。

只有有付费资格的账号才能通过 API 创建任务（否则是 403 not_eligible），而且 API 只扣付费积分（不够时是 402 insufficient_credits）。赠送积分和签到积分只留给网站使用。

生成 API 接口

所有路径都在本站上。请求体和响应体都是 JSON，结果文件除外。

https://demo.freshapp.ai

模型和价格

本站已启用的模型，按 API 的写法列出：把编号填进 model，把字段填进 input。请求在创建时预留它最贵的可能结果，结束后按实际交付的部分收费。

幂等键

创建生成任务必须带 Idempotency-Key 请求头，由 1 到 128 个字母、数字、点、冒号、下划线或连字符组成。建议用你自己系统里的编号，比如订单号，这样同一件事总是用同一个键。

同一个键加同样的请求，不管发多少次都返回同一个任务，只扣一次费。同一个键加不同的请求会得到 409 idempotency_conflict，不会创建任何任务。

超时或连接中断并不代表请求失败。请用同一个键和同样的请求体再发一次，并在收到回复之前一直保留这两样。5xx、429 和 408 也一样处理：按 Retry-After 等待，然后原样再发一次。

状态和轮询

用 GET /api/v1/generations/{id} 查询任务：开始时每 5 秒一次，之后最长每 10 秒一次，直到状态结束。遇到 429 时，Retry-After 会告诉你什么时候再查。

billing.reserved_credits 是创建任务时预留的积分。结算后，charged_credits 是实际收取的积分，refunded_credits 是退回的积分；结算之前两者都是 null，held_credits 显示正在占用的积分。

等待人工核对的任务会在 review 里显示核对开始的时间，核对结束前积分一直占用；核对后任务继续，或者积分退回。

结果文件

每个已交付的输出都有一个本站上的 url。用密钥查询时，它是一个签名链接，一小时内不带密钥、从任何地址都能打开，可以直接交给下载工具。超过一小时后，再查一次任务就能拿到新的链接。

用密钥本身请求 GET /api/media/{id} 也能拿到文件，但受这把密钥的白名单限制。两种方式都支持 HEAD 和一个字节范围（Range: bytes=0-1023），并且不会跳转到别的网站。

输入里引用的文件（比如一段音频样本或一张图片）必须是这个账号在网站上上传的、本站自带的样本，或者来自本站允许的来源的链接；其他引用在预留积分之前就会被拒绝。

限额

下面每一项都是本站当前执行的限额，每次拒绝都会说明碰到了哪一项。

• 一次请求最多预留 150 积分，即已启用模型中最贵一次请求的费用。可以给密钥设得更低，请求里的 max_credits 能为这一次再调低；超过时返回 400 request_limit_exceeded。
• 每把密钥每个 UTC 日最多花 5,000 积分，可以自己设置，最高 1,000,000；超过后这把密钥得到 429 key_daily_limit_exceeded，直到下一个 UTC 日。
• 一个账号的所有密钥加上它授权的 AI 客户端，每个 UTC 日合计最多花 10,000 积分，可以为账号另设上限；超过后返回 429 account_daily_limit_exceeded。
• 每把密钥和每个账号每分钟最多创建和取消 20 次、查询和下载 240 次；超过后返回 429 rate_limited，并带 Retry-After。
• 一个账号同时运行的生成任务最多 2 个；再创建会得到 429 too_many_active。
• 请求体最多 32 KiB 的 JSON；更大的返回 413 request_too_large。

错误码

错误的格式是 {"error": {"code": …, "message": …}}。code 一定是下表中的一个，message 是写给开发者的英文说明。429 和 503 会在 Retry-After 里给出需要等待的秒数。失败或被取消的任务会在 error 字段里带上标为任务错误的码之一。

TypeScript 客户端和 React hook

TypeScript 客户端 open-api-client.ts 不需要任何其他包，可以在服务器、Worker 和浏览器里运行。在服务器上传入 baseUrl 和 apiKey；在本站的浏览器页面里两者都不传，请求会使用访客自己的登录状态。

create 会发送 Idempotency-Key（你给的，或者新生成的随机值），遇到连接中断、5xx、429 或 408 时用同一个请求重发，并按 Retry-After 等待。放弃时，错误里带着这个键，你可以稍后用它重发。传入 store（比如 localStorage）后，刷新页面也会沿用第一次的键。

wait 会一直查询任务直到结束：开始时间隔 5 秒，之后最长 10 秒，中止时立刻停下。download 下载一个输出的文件，只对本站自己的未签名链接带上密钥。

React hook open-api-react.ts 用客户端的 wait 跟进一个任务，组件卸载时停止。下载这两个文件，放在同一个目录下，并把扩展名改成 .ts。

文件下载