Seedream 5.0 Pro API

Keupayaan

Harga & kredit

Harga di bawah adalah bagi setiap imej yang dikembalikan. Penjanaan biasa memperuntukkan kredit untuk satu imej, manakala penghuraian lapisan memperuntukkan kredit untuk 17 imej. Caj akhir dikira berdasarkan bilangan imej yang benar-benar dikembalikan, termasuk imej asas, dan kredit yang tidak digunakan dipulangkan ke baki asal. Tugasan yang gagal menerima bayaran balik penuh.

Pada resolusi lalai 2K, penghuraian lapisan menempah 136 kredit. Jika empat imej dikembalikan, caj akhir ialah 32 kredit dan 104 kredit dikembalikan.

Keidempotensian permintaan tidak disokong. Setiap POST yang sah akan membuat tugasan berbayar yang baharu. Jika status penyerahan tidak pasti, tanya taskId yang dikembalikan; mencuba semula POST boleh membuat tugasan lain.

Pengesahan

Cipta kunci API dalam papan pemuka. Kunci lengkap hanya akan dipaparkan sekali sahaja. Simpan kunci ini pada pelayan anda dan hantarkannya sebagai token Bearer dalam setiap permintaan.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Tetapkan pemboleh ubah persekitaran SEEVIO_API_KEY sebelum menjalankan contoh ini. Contoh JavaScript dijalankan pada pelayan anda dengan Node.js; contoh Python menggunakan pakej requests.

Badan permintaan

Parameter input

Setiap permintaan akan mencipta satu tugas. Teks-ke-imej dan imej-ke-imej memulangkan satu imej; penguraian lapisan (layer-decomposition) memulangkan 1–17 imej, termasuk imej asas. Jangan hantar aspect_ratio untuk penguraian lapisan.

Mula cepat

Hantar permintaan ringkas ini, simpan taskId yang dikembalikan, kemudian gunakan contoh pertanyaan tugasan di bawah. Nilai kredit dalam respons penciptaan ialah amaun yang ditempah.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Contoh respons cipta tugasan

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 8
}

Teks kepada imej

Jana imej, sunting imej rujukan atau pisahkan imej kepada lapisan dengan kunci API Seevio anda. Tugasan dijalankan secara tak segerak; simpan taskId dan semak titik akhir tugasan secara berkala atau terima panggilan balik.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Imej kepada imej

Untuk pengeditan imej, tetapkan generation_type kepada image-to-image dan sediakan image_urls. Semua parameter lain menggunakan kontrak yang sama.

Gantikan URL media contoh.com dengan fail HTTPS anda sendiri yang boleh diakses secara awam. URL contoh disediakan hanya untuk menunjukkan struktur permintaan dan bukannya aset sampel yang boleh dimuat turun.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

Penghuraian lapisan

Tetapkan generation_type kepada layer-decomposition dan sediakan tepat satu URL imej. Jangan sertakan aspect_ratio. output_format hanya mengawal format imej asas. Lapisan yang dipisahkan sentiasa dikembalikan sebagai PNG dengan ketelusan yang dipelihara. Simpan setiap URL yang dikembalikan dalam data.results.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "generation_type": "layer-decomposition",
    "image_urls": [
      "https://example.com/teapot.png"
    ],
    "resolution": "2K",
    "output_format": "png"
  }
}'

Penghuraian lapisan boleh mengembalikan beberapa URL imej dalam data.results: imej asas dan lapisan yang dipisahkan. Setiap URL menunjuk ke imej yang berbeza. Bilangan hasil berbeza mengikut tugasan (1–17 imej secara keseluruhan); proses keseluruhan tatasusunan dan bukannya hanya data.results[0]. Kedua-dua pertanyaan tugasan yang selesai dan webhook penyelesaian mengandungi tatasusunan ini. Respons cipta awal mengandungi taskId dan kredit yang dikhaskan, bukan URL imej.

Contoh respons cipta tugasan

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 136
}

Penghuraian lapisan selesai: berbilang URL imej

Respons ilustrasi ini menunjukkan empat imej output: satu imej asas dan tiga lapisan. Tugasan anda mungkin mengembalikan bilangan imej yang berbeza. Pada resolusi 2K yang diminta, credits ialah caj akhir untuk kesemua empat imej; bahagian tempahan 17 imej awal yang tidak digunakan telah dikembalikan.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 32,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example/base.png",
      "https://cdn.seevio.ai/api/images/example/layer-1.png",
      "https://cdn.seevio.ai/api/images/example/layer-2.png",
      "https://cdn.seevio.ai/api/images/example/layer-3.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

Proses setiap imej yang dikembalikan

const response = await fetch(
  "https://api.seevio.ai/v1/tasks/TASK_ID",
  { headers: { Authorization: `Bearer ${process.env.SEEVIO_API_KEY}` } }
);
if (!response.ok) throw new Error(await response.text());
const task = await response.json();

if (task.status === "completed") {
  // Process every returned image, including the base image.
  // The number of URLs varies; do not read only results[0].
  for (const [index, imageUrl] of task.data.results.entries()) {
    console.log({ taskId: task.id, index, imageUrl });
    // Download or store this image in your application.
  }
} else if (task.status === "failed") {
  throw new Error(task.failed_reason || "Image generation failed.");
}
// If queued or generating, poll again after at least 5 seconds.

Tanya status tugasan

Gantikan ID contoh dengan taskId yang dikembalikan semasa penciptaan. Pertanyaan hanya mengembalikan tugasan milik pengguna kunci API tersebut; ID yang tidak boleh diakses atau tidak dikenali akan mengembalikan ralat HTTP 404.

Lakukan pengundian (polling) setiap 10–20 saat sebagai permulaan, kurangkan kekerapan jika menerima ralat HTTP 429, dan hentikan apabila status bertukar kepada completed atau failed. Sebaik-baiknya gunakan webhook untuk persekitaran pengeluaran. Setiap contoh kod di bawah melakukan satu pertanyaan.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

Dalam baris gilir

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

Selesai

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

Gagal

Apabila pertanyaan mengembalikan status=failed, ini bermakna penjanaan telah tamat tetapi gagal. Rujuk failed_reason untuk mengetahui punca kegagalan dan billing_status untuk status bayaran balik. Dalam contoh ini, refunded bermakna kredit telah dikembalikan semula. credits mengekalkan amaun asal yang diketepikan, dan respons ini tidak mengandungi data.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs."
}

Pautan hasil disediakan selama 30 hari selepas disimpan. Selepas tamat tempoh, bahagian results akan dikosongkan.

Webhook

Tetapkan callback_url dalam permintaan cipta untuk menerima POST JSON apabila tugasan selesai atau gagal. Kembalikan respons 2xx dalam masa 15 saat. Penghantaran yang gagal akan dicuba semula; proses penghantaran berulang secara idempotensi menggunakan ID tugasan.

Pangkalan akhir (endpoint) panggilan balik anda mesti menerima permintaan POST dengan badan permintaan JSON (Content-Type: application/json).

Cipta tugasan dengan panggilan semula

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Panggilan balik (callback) menggunakan struktur respons pertanyaan tugasan; pemberitahuan kegagalan yang telah dibayar balik juga menyertakan credits_refunded pada peringkat tertinggi. Gunakan id untuk mengenal pasti tugasan dan status untuk membezakan status selesai atau gagal. Pemberitahuan mungkin berulang: proses secara idempoten mengikut id dan status. Panggilan balik tidak ditandatangani; sahkan tugasan dengan titik akhir pertanyaan yang memerlukan pengesahan identiti. Kegagalan penghantaran tidak akan mengembalikan kredit bagi tugasan yang berjaya.

Tugasan selesai: muatan panggilan balik yang berjaya

created_at ialah masa penciptaan peristiwa; task_created_at ialah masa penciptaan tugasan, dalam saat Unix. Contoh menunjukkan medan yang disyorkan; respons mungkin mengandungi medan tambahan.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

Tugasan gagal: muatan panggilan balik yang gagal

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs.",
  "task_created_at": 1789171200,
  "credits_refunded": 8
}

Contoh penerima

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const imageUrls = callbackData.data.results;
    // Save the image URLs and mark this task as completed in your application.
    console.log(callbackData.id, imageUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

Contoh Next.js ini membaca badan panggilan balik JSON dan mengendalikan tugasan yang selesai serta gagal secara terus. Tambahkan fungsi persistensi dan penyahduplikasian ID tugasan untuk aplikasi anda; masukkan kerja yang lambat ke dalam giliran (queue) sebelum mengesahkan panggilan balik.

Ralat

Ralat HTTP mengandungi objek ralat dengan kod dan mesej. Tugasan yang berjaya diterima masih boleh gagal kemudian; tanya status tugasan atau kendalikan panggilan semula kegagalannya.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

Ralat menggunakan error.code dan error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Ralat 402 insufficient_credits bermaksud baki kredit anda tidak mencukupi untuk permintaan ini.

Had kadar

Cipta tugasan: setiap kunci API membenarkan sehingga 100 permintaan seminit secara lalai. Had kadar tersuai tidak ditawarkan buat masa ini.

Kueri tugasan: setiap kunci API membenarkan sehingga 120 permintaan seminit secara lalai. Permintaan kueri dan permintaan penciptaan tugasan dikira secara berasingan.

Permintaan penciptaan imej dan video berkongsi had kadar kunci API yang sama.

HTTP 429 menyertakan Retry-After: 60 untuk penciptaan dan Retry-After: 5 untuk pertanyaan. Gunakan fungsi undur masa (backoff) dan elakkan daripada melakukan pengundian lebih kerap daripada yang diperlukan.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}