Dokumentasi API generasi

Membuat generasi lewat API memerlukan paket kredit berbayar atau langganan berbayar yang aktif, dan hanya memakai kredit berbayar. Membaca, mendaftar, dan mengunduh bisa dilakukan dengan kunci apa pun dari akun itu.

Mulai cepat

Buat kunci di halaman kunci API, simpan di server Anda, dan jadikan API_KEY. Contoh-contoh ini membuat generasi dengan seed-audio-1.0, membacanya sampai selesai, lalu mengunduh file pertamanya.

Kirim Idempotency-Key baru untuk setiap permintaan baru. Jika permintaan tidak mendapat jawaban, kirim lagi dengan kunci yang sama dan isi yang sama: Anda mendapat generasi yang dibuat permintaan pertama, dan ditagih sekali saja.

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":"Mercusuar di atas tebing saat fajar, laut tenang, cahaya lembut."}}'

# 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": "Mercusuar di atas tebing saat fajar, laut tenang, cahaya lembut."
    }
  },
  { 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>;
}

Kunci dan izin

Setiap permintaan membawa Authorization: Bearer dengan kunci dari halaman kunci API. Kunci berupa sk_ diikuti 43 huruf, angka, tanda hubung, atau garis bawah, dan hanya ditampilkan sekali, saat dibuat atau dirotasi. Permintaan dengan Authorization dinilai hanya dari kuncinya, tidak pernah dari sesi login di sampingnya.

Kunci hanya bisa membaca (mendaftar, membaca, dan mengunduh) atau juga bisa menghasilkan (membuat dan membatalkan). Kunci baca-saja mendapat 403 insufficient_scope saat mencoba membuat atau membatalkan, dan tidak ada yang ditulis.

Kunci bisa membawa daftar IP yang diizinkan berisi alamat dan jaringan: dari alamat lain ia mendapat 403 ip_not_allowed. Memberi kunci izin lebih, menaikkan batas, atau memperluas daftar memerlukan login baru-baru ini; mempersempitnya tidak.

Merotasi kunci langsung memberinya nilai baru dan nilai lama berhenti. Mencabut kunci menghentikannya untuk selamanya: generasinya yang belum dikirim ke model dibatalkan dan kreditnya kembali, sedangkan yang sudah berjalan tetap selesai.

Hanya akun dengan akses berbayar yang bisa membuat generasi lewat API (jika tidak, 403 not_eligible), dan API hanya memakai kredit berbayar (402 insufficient_credits). Kredit hadiah dan check-in tetap untuk situs web.

Endpoint API generasi

Semua jalur ada di situs ini. Isi permintaan dan respons berupa JSON, kecuali file hasil.

https://demo.freshapp.ai

Model dan harga

Model yang aktif di situs ini, sebagaimana API menerimanya: pakai id sebagai model, dan field sebagai input. Permintaan menahan hasil termahalnya saat dibuat; saat selesai, Anda membayar yang terkirim.

Idempotensi

Membuat generasi memerlukan header Idempotency-Key berisi 1 sampai 128 huruf, angka, titik, titik dua, garis bawah, atau tanda hubung. Pakai id dari sistem Anda sendiri, seperti nomor pesanan, agar pekerjaan yang sama selalu mendapat kunci yang sama.

Kunci yang sama dengan permintaan yang sama mengembalikan generasi yang sama, berapa kali pun dikirim, dan ditagih sekali. Kunci yang sama dengan permintaan berbeda menghasilkan 409 idempotency_conflict, dan tidak ada yang dibuat.

Waktu habis atau koneksi terputus tidak berarti permintaan gagal. Kirim lagi dengan kunci yang sama dan isi yang sama, dan simpan keduanya sampai Anda mendapat jawaban. 5xx, 429, atau 408 ditangani dengan cara yang sama: tunggu sesuai Retry-After, lalu kirim lagi permintaan itu tanpa perubahan.

Status dan polling

Baca generasi dengan GET /api/v1/generations/{id} setiap 5 detik di awal, lalu paling lambat setiap 10 detik, sampai statusnya selesai. 429 menyebutkan di Retry-After kapan membaca lagi.

billing.reserved_credits adalah yang ditahan saat generasi dibuat. Setelah diselesaikan, charged_credits adalah yang Anda bayar dan refunded_credits yang kembali; sebelum itu keduanya null dan held_credits menunjukkan yang sedang ditahan.

Generasi yang menunggu pemeriksaan manual menampilkan review beserta waktu pemeriksaan dimulai, dan tetap menahan kreditnya sampai pemeriksaan selesai; setelah itu ia berlanjut atau kreditnya kembali.

File hasil

Setiap output yang terkirim punya url di situs ini. Untuk kunci, itu adalah tautan bertanda tangan yang berlaku satu jam tanpa kunci dan dari alamat mana pun, jadi bisa Anda berikan ke alat pengunduh. Setelah satu jam, baca lagi generasinya untuk mendapat tautan baru.

Dengan kunci itu sendiri, GET /api/media/{id} juga mengembalikan file, dalam batas daftar IP kunci. Keduanya menerima HEAD dan satu rentang byte (Range: bytes=0-1023), dan tidak pernah dialihkan ke situs lain.

File yang dirujuk dalam input, seperti sampel audio atau gambar, harus diunggah oleh akun ini di situs web, salah satu sampel milik situs, atau tautan dari sumber yang diizinkan situs; selain itu ditolak sebelum kredit ditahan.

Batas

Setiap batas di bawah ini adalah yang diterapkan situs ini sekarang, dan setiap penolakan menyebutkan batas mana yang tercapai.

• Satu permintaan menahan paling banyak 150 kredit, yaitu permintaan termahal dari model yang aktif. Kunci bisa diatur lebih rendah, dan max_credits pada permintaan menurunkannya untuk permintaan itu; di atasnya jawabannya 400 request_limit_exceeded.
• Setiap kunci menghabiskan paling banyak 5.000 kredit per hari UTC kecuali Anda menetapkan batasnya sendiri, hingga 1.000.000; setelah lewat, kunci mendapat 429 key_daily_limit_exceeded sampai hari UTC berikutnya.
• Semua kunci satu akun, bersama klien AI-nya, menghabiskan paling banyak 10.000 kredit per hari UTC kecuali Anda menetapkan batas akun sendiri; setelah lewat, jawabannya 429 account_daily_limit_exceeded.
• Setiap kunci dan setiap akun mengirim paling banyak 20 pembuatan dan pembatalan serta 240 pembacaan dan unduhan per menit; setelah lewat, 429 rate_limited dengan Retry-After.
• Paling banyak 2 generasi satu akun berjalan bersamaan; generasi lain menunggu dengan 429 too_many_active.
• Isi permintaan paling besar 32 KiB JSON; yang lebih besar menghasilkan 413 request_too_large.

Kode galat

Galat berbentuk {"error": {"code": …, "message": …}}. Kodenya selalu salah satu dari daftar ini, dan pesannya dalam bahasa Inggris untuk pengembang. 429 atau 503 menyebutkan di Retry-After berapa detik harus menunggu. Generasi yang gagal atau dibatalkan membawa salah satu kode yang ditandai sebagai milik generasi di field error-nya.

Klien TypeScript dan hook React

Klien TypeScript, open-api-client.ts, tidak membutuhkan paket lain dan berjalan di server, worker, dan browser. Di server, berikan baseUrl dan apiKey; di browser pada situs ini, jangan berikan keduanya, dan permintaan memakai sesi milik pengunjung sendiri.

create mengirim Idempotency-Key, milik Anda atau nilai acak baru, dan mengirim ulang permintaan yang sama setelah koneksi terputus, 5xx, 429, atau 408, sambil menunggu sesuai Retry-After. Saat menyerah, galatnya membawa kunci itu, sehingga Anda bisa mengirim ulang permintaan nanti. Dengan store seperti localStorage, permintaan tetap memakai kunci pertamanya setelah halaman dimuat ulang.

wait membaca generasi sampai selesai, setiap 5 detik di awal lalu paling lambat 10, dan berhenti saat Anda membatalkannya. download mengambil file sebuah output, dan hanya mengirim kunci ke tautan tanpa tanda tangan milik situs ini.

Hook React, open-api-react.ts, memantau satu generasi dengan wait milik klien dan berhenti saat komponen dilepas. Unduh kedua file, letakkan berdampingan, dan ganti ekstensinya menjadi .ts.

Unduhan