生成 API ドキュメント

API で生成を作成するには、有料のクレジットパックか有効な有料サブスクリプションが必要で、使われるのは有料クレジットだけです。読み取り、一覧、ダウンロードはアカウントのどのキーでもできます。

クイックスタート

API キーのページでキーを作成し、サーバーにだけ置いて API_KEY に設定します。以下の例では seed-audio-1.0 で生成を作成し、終わるまで読み取って、最初のファイルをダウンロードします。

新しいリクエストごとに新しい Idempotency-Key を送ります。応答がなかったときは、同じキーと同じ本文で送り直してください。最初のリクエストが作った生成が返り、請求は 1 回だけです。

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>;
}

キーと権限

すべてのリクエストは、API キーのページで作成したキーを Authorization: Bearer に付けて送ります。キーは 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 での書き方で示します。ID を model に、フィールドを input に指定してください。リクエストは作成時に最も高くなる場合の額を確保し、終わったら納品された分だけ支払います。

冪等性

生成の作成には、1〜128 文字の英数字、ピリオド、コロン、アンダースコア、ハイフンからなる Idempotency-Key ヘッダーが必要です。注文番号など自分のシステムの ID を使えば、同じ作業にはいつも同じキーが付きます。

同じキーと同じリクエストなら、何度送っても同じ生成が返り、請求は 1 回だけです。同じキーで別のリクエストを送ると 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 があります。キーで読み取った場合は署名付きリンクで、1 時間はキーなしでどのアドレスからでも開けるので、そのままダウンロードツールに渡せます。1 時間を過ぎたら、生成をもう一度読み取って新しいリンクを受け取ってください。

キーそのものを使って GET /api/media/{id} からファイルを取得することもでき、その場合はキーの許可リストが適用されます。どちらも HEAD と 1 つのバイト範囲（Range: bytes=0-1023）に対応し、ほかのサイトへリダイレクトすることはありません。

入力で参照するファイル（音声サンプルや画像など）は、このアカウントがウェブサイトでアップロードしたもの、当サイトのサンプル、または当サイトが許可するソースへのリンクである必要があります。それ以外はクレジットを確保する前に拒否されます。

上限

以下はいずれも当サイトがいま適用している上限で、拒否されたときはどれに達したかが示されます。

• 1 回のリクエストで確保できるのは最大 150 クレジットで、有効なモデルのうち最も高いリクエストの料金です。キーにもっと低い値を設定でき、リクエストの max_credits でその回だけさらに下げられます。超えると 400 request_limit_exceeded になります。
• キーごとに 1 UTC 日あたり最大 5,000 クレジットで、キーごとの上限を最大 1,000,000 まで設定できます。超えたキーは次の UTC 日まで 429 key_daily_limit_exceeded になります。
• アカウントのすべてのキーとその AI クライアントの合計は、1 UTC 日あたり最大 10,000 クレジットで、アカウント独自の上限も設定できます。超えると 429 account_daily_limit_exceeded になります。
• キーごと・アカウントごとに、1 分あたり作成とキャンセルは 20 回、読み取りとダウンロードは 240 回までです。超えると Retry-After 付きの 429 rate_limited になります。
• 1 つのアカウントで同時に実行できる生成は最大 2 件で、それ以上は 429 too_many_active で待つことになります。
• リクエスト本文は最大 32 KiB の JSON で、それより大きいと 413 request_too_large になります。

エラーコード

エラーは {"error": {"code": …, "message": …}} の形で返ります。code は必ず次の表のどれかで、message は開発者向けの英語の説明です。429 と 503 では、待つ秒数が Retry-After に入ります。失敗またはキャンセルされた生成は、生成用と記されたコードのどれかを error フィールドに持ちます。

TypeScript クライアントと React フック

TypeScript クライアント open-api-client.ts はほかのパッケージを必要とせず、サーバー、ワーカー、ブラウザで動きます。サーバーでは baseUrl と apiKey を渡し、当サイト上のブラウザではどちらも渡さなければ、訪問者自身のログイン状態でリクエストします。

create は Idempotency-Key（指定したもの、または新しいランダム値）を送り、接続の切断、5xx、429、408 のときは Retry-After のとおり待ってから同じリクエストを送り直します。あきらめたときはエラーにキーが入っているので、あとでそのキーで送り直せます。localStorage などの store を渡すと、ページを再読み込みしても最初のキーが使われます。

wait は生成を終わるまで読み取ります。間隔は最初 5 秒、その後は最長 10 秒で、中止するとすぐに止まります。download は出力のファイルを取得し、キーを付けるのは当サイト自身の署名なしリンクだけです。

React フック open-api-react.ts はクライアントの wait で生成を 1 件追跡し、コンポーネントがアンマウントされると止まります。2 つのファイルをダウンロードして同じ場所に置き、拡張子を .ts に変えてください。

ダウンロード