เอกสาร 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) เครดิตของขวัญและเครดิตเช็กอินเก็บไว้ใช้บนเว็บไซต์

Endpoint ของ API สำหรับการสร้างงาน

ทุกเส้นทางอยู่บนเว็บไซต์นี้ เนื้อหาคำขอและคำตอบเป็น JSON ยกเว้นไฟล์ผลลัพธ์

https://demo.freshapp.ai

โมเดลและราคา

โมเดลที่เปิดใช้งานบนเว็บไซต์นี้ในรูปแบบที่ API รับ ใส่รหัสใน model และใส่ฟิลด์ใน input คำขอจะกันเครดิตตามผลลัพธ์ที่แพงที่สุดตอนสร้าง และเมื่อจบคุณจ่ายตามที่ส่งมอบจริง

การส่งซ้ำอย่างปลอดภัย (Idempotency)

การสร้างงานต้องมีส่วนหัว 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} ก็ได้ไฟล์เช่นกัน ภายใต้รายการ IP ที่อนุญาตของคีย์ ทั้งสองวิธีรองรับ HEAD และช่วงไบต์หนึ่งช่วง (Range: bytes=0-1023) และจะไม่เปลี่ยนเส้นทางไปเว็บไซต์อื่น

ไฟล์ที่อ้างอิงในอินพุต เช่น ตัวอย่างเสียงหรือภาพ ต้องเป็นไฟล์ที่บัญชีนี้อัปโหลดบนเว็บไซต์ ตัวอย่างของเว็บไซต์เอง หรือลิงก์จากแหล่งที่เว็บไซต์อนุญาต นอกนั้นจะถูกปฏิเสธก่อนกันเครดิต

ขีดจำกัด

ขีดจำกัดด้านล่างทุกข้อคือค่าที่เว็บไซต์นี้ใช้อยู่ตอนนี้ และทุกการปฏิเสธจะบอกว่าชนขีดจำกัดใด

• คำขอหนึ่งครั้งกันเครดิตได้สูงสุด 150 เครดิต ซึ่งเป็นคำขอที่แพงที่สุดของโมเดลที่เปิดใช้งาน ตั้งคีย์ให้ต่ำกว่านี้ได้ และ max_credits ในคำขอจะลดค่านี้สำหรับคำขอนั้น หากเกินจะได้ 400 request_limit_exceeded
• แต่ละคีย์ใช้ได้สูงสุด 5,000 เครดิตต่อวัน UTC เว้นแต่คุณจะตั้งขีดจำกัดของคีย์เอง ได้สูงสุด 1,000,000 หากเกิน คีย์จะได้ 429 key_daily_limit_exceeded จนถึงวัน UTC ถัดไป
• ทุกคีย์ของบัญชีรวมกับไคลเอนต์ AI ของบัญชีใช้ได้สูงสุด 10,000 เครดิตต่อวัน UTC เว้นแต่คุณจะตั้งขีดจำกัดของบัญชีเอง หากเกินจะได้ 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

ดาวน์โหลด