how-tos

Ideogram 4.6 API: Panduan Gambar dan Edit Pertama dengan cURL dan Python

Poyo.ai Team
8 min read
Share:

Panduan Ideogram 4.6 API dengan cURL dan Python

Panduan Ideogram 4.6 API ini membawa Anda dari API key hingga gambar jadi dengan cURL dan Python, lalu membahas setiap mode input yang diterima skema PoYo: text-to-image dengan ukuran preset atau kustom, background transparan, edit reguler, edit dengan mask, gambar referensi, dan edit presisi tinggi. Text-to-image memakai ID model ideogram-v4.6 dan pengeditan memakai ideogram-v4.6-edit; keduanya tercantum di halaman model Ideogram 4.6.

Aturan field berasal dari referensi API PoYo. Untuk mengetahui apa model ini dan bagaimana perbandingannya, mulailah dari ikhtisar Ideogram 4.6 API.

Langkah 1: kirim request Ideogram 4.6 API dengan cURL

Buat key di dashboard PoYo dan export sebagai POYO_API_KEY. Simpan di server Anda, jangan di kode browser.

curl https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v4.6",
    "input": {
      "prompt": "A colorful storefront with a neon sign reading \"HELLO\""
    }
  }'

Request ini memakai nilai default: size: auto (sekitar 2K), quality: medium, satu gambar, sehingga biayanya 12 kredit ($0.06). Submit yang berhasil mengembalikan code: 200 dan objek data berisi task_id, status: "not_started", dan created_time. Itu adalah task dalam antrean, bukan gambar. Periksa code di body setiap kali: beberapa error validasi kembali dengan HTTP 200 dan code: 400.

Langkah 2: polling status task

curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Status bergerak dari not_started, running, lalu finished atau failed. Task yang selesai mencantumkan satu entri per gambar di data.files, masing-masing dengan file_url dan file_type: "image", serta melaporkan biaya di credits_amount. Task yang gagal menjelaskan penyebabnya di error_message.

Langkah 3: loop polling Python yang dibatasi waktu

Loop ini memeriksa status HTTP sekaligus code di body, berhenti saat failed, mengembalikan semua gambar ketika n lebih dari 1, dan menyerah setelah 10 menit tanpa mengirim ulang.

import os
import time
import requests

BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]

def checked(response):
    body = response.json()
    if response.status_code >= 400 or body.get("code") != 200:
        error = body.get("error") or {}
        raise RuntimeError(f"PoYo error {body.get('code')}: {error.get('message', body)}")
    return body["data"]

def run(model, input_body, max_wait=600):
    task = checked(session.post(BASE + "/api/generate/submit",
                                json={"model": model, "input": input_body},
                                timeout=60))
    task_id = task["task_id"]
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        time.sleep(5)
        task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
        if task["status"] == "failed":
            raise RuntimeError(task.get("error_message") or "generation failed")
        if task["status"] == "finished":
            images = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
            return images, task.get("credits_amount")
    raise TimeoutError("Still running, check this task later: " + task_id)

images, credits = run("ideogram-v4.6", {
    "prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
    "size": "1728x2304",
    "quality": "high",
    "n": 2,
})
print(images, credits)

1728x2304 adalah ukuran 3:4 sebesar 3,981,312 piksel, di bawah batas 4,194,304 piksel, sehingga kedua gambar ditagih dengan tarif 2K high: 2 × 20 = 40 kredit ($0.20). Timeout berarti "periksa lagi ID task yang sama nanti". Mengirim ulang akan memulai task kedua yang juga ditagih. Fungsi run() yang sama berlaku untuk edit: berikan "ideogram-v4.6-edit" sebagai model.

Semua mode input Ideogram 4.6 API

Semua field berada di dalam input. ID model dan callback_url opsional berada di level teratas.

Text-to-image pada 4K

{
  "model": "ideogram-v4.6",
  "input": {
    "prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
    "size": "2048x3072",
    "quality": "high",
    "n": 2
  }
}

2048x3072 berarti 6,291,456 piksel, di atas 4,194,304, jadi ini tingkatan 4K dan very_low tidak diizinkan pada ukuran ini.

Background transparan dan seed tetap

{
  "model": "ideogram-v4.6",
  "input": {
    "prompt": "A flat sticker of a smiling coffee cup",
    "size": "1:1 HD",
    "quality": "low",
    "background": "transparent",
    "seed": 42
  }
}

transparent mengembalikan gambar dengan alpha channel; opaque memaksa background solid. Kirim body yang sama dengan seed yang sama untuk mengulang hasil.

Edit reguler

{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Replace the background with a blue photo studio",
    "image_urls": [
      "https://example.com/source.png"
    ]
  }
}

Edit reguler membuat ulang gambar dari prompt. image_urls harus berupa array berisi tepat satu gambar, sebagai URL HTTP(S) publik atau data URI base64. Untuk mengirim file lokal, unggah dulu dengan endpoint upload file PoYo.

Ubah gaya dengan gambar referensi

{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Restyle the product shot to match the reference",
    "image_urls": [
      "https://example.com/product.png"
    ],
    "reference_image_urls": [
      "https://example.com/style.png"
    ],
    "size": "2048x2048",
    "quality": "low",
    "n": 2
  }
}

Hingga 4 referensi diizinkan, atau 3 jika memakai mask. size kustom diizinkan di sini karena ini edit reguler tanpa mask.

Edit presisi tinggi untuk seluruh gambar

{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Change only the date line to \"JULY 3-5 · RIVERSIDE PARK\". Keep everything else exactly the same.",
    "image_urls": [
      "https://example.com/poster.png"
    ],
    "edit_precision": "high",
    "context_window": "none",
    "size": "auto",
    "quality": "high"
  }
}

Ini adalah body edit hari peluncuran kami (task 672JRU198S22NS8D, 20 November 2026), dengan URL sumber yang diganti. Sumbernya adalah poster 2304×3072; output mempertahankan ukuran itu dan hanya mengubah baris tanggal, dan task ditagih 120 kredit ($0.60), tarif edit 4K high.

Edit lokal dengan mask

{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Change the sign text to \"OPEN LATE\"",
    "image_urls": [
      "https://example.com/storefront.png"
    ],
    "mask_url": "https://example.com/sign-mask.png",
    "edit_precision": "high",
    "context_window": "auto",
    "quality": "high"
  }
}

Mask harus memiliki dimensi yang sama dengan sumber dan berisi area hitam (diedit) dan putih (dipertahankan). Dengan context_window: auto, hanya area di sekitar mask yang diedit pada resolusi sumber. Mask yang terlalu besar akan kembali ke pengeditan seluruh gambar.

Aturan validasi field

Lakukan validasi di sisi Anda sebelum submit agar request yang salah langsung gagal:

FieldAturan
modelideogram-v4.6 atau ideogram-v4.6-edit
promptWajib, 1 sampai 10,000 karakter, tidak hanya spasi
sizeauto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 atau WIDTHxHEIGHT dengan x huruf kecil
Ukuran kustomSetiap sisi 256 sampai 4096 dan kelipatan 32; rasio aspek antara 1:6 dan 6:1
qualityvery_low hanya jika output paling banyak 4,194,304 piksel
nBilangan bulat 1 sampai 8; string dan boolean ditolak
image_urlsHanya untuk edit; array berisi tepat satu gambar
mask_url, edit_precision: highMembutuhkan size: auto (atau tanpa size)
backgroundDitolak jika edit_precision bernilai high
context_window: autoMembutuhkan mask_url dan edit_precision: high
Field tidak dikenalDitolak dengan error unsupported fields

Contoh: 2304x3072 lolos (kedua sisi kelipatan 32); 1296x3168 gagal karena 1296 bukan kelipatan 32, meskipun Ideogram 4.5 menerimanya; 4096x512 gagal (rasio 8:1); very_low pada 2048x3072 gagal.

Error yang perlu ditangani

codeArtiYang harus dilakukan
400Parameter tidak validPerbaiki body; jangan coba ulang tanpa perubahan
401API key tidak ada atau tidak validPeriksa header Authorization: Bearer
402Kredit tidak cukupIsi ulang, lalu kirim ulang
429Batas rate terlampauiMundur sejenak dan coba lagi nanti
500, 502, 503Error server, upstream, atau ketersediaanCoba ulang dengan backoff; periksa dulu apakah ID task sudah dikembalikan

Task yang mencapai failed membawa penyebabnya di error_message. Lihat Error Codes untuk daftar lengkap.

Gunakan callback alih-alih polling

Tambahkan "callback_url": "https://your-app.example.com/poyo-webhook" di level teratas body, bukan di dalam input. Saat task selesai atau gagal, PoYo mengirim POST berisi data task ke URL tersebut, ditandatangani dengan HMAC-SHA256 di header X-Webhook-Signature; dokumentasi webhook menjelaskan aturan tanda tangannya. Tetap siapkan polling lambat sebagai cadangan untuk callback yang tidak pernah tiba.

Cara tagihan pertama Anda dihitung

Ideogram 4.6 API menagih per gambar output: harga tingkatan kualitas dan ukuran × n. 1 kredit = $0.005.

RequestTingkatanBiaya
Default (auto, medium, n: 1)Text-to-image medium 2K12 kredit ($0.06)
very_low, 3:4, n: 1Text-to-image very_low 2K1.6 kredit ($0.008)
high, 1728x2304, n: 2Text-to-image high 2K40 kredit ($0.20)
high, 2304x3072, n: 1Text-to-image high 4K40 kredit ($0.20)
Edit presisi tinggi dari sumber 2304×3072, highEdit high 4K120 kredit ($0.60)

Baris very_low dan 2304x3072 sama dengan yang ditagihkan pada task hari peluncuran kami. Untuk edit dengan size: auto, harga diperkirakan dari ukuran gambar sumber dan diselesaikan berdasarkan gambar yang dikirim, tidak pernah melebihi perkiraan. Artikel harga berisi lebih banyak contoh perhitungan.

Pertanyaan yang sering diajukan

Apakah Ideogram 4.6 API kompatibel dengan OpenAI SDK? Tidak. Ini adalah API task asinkron: submit ke /api/generate/submit, lalu polling /api/generate/status/{task_id} atau terima callback. requests, fetch, atau cURL biasa sudah cukup.

Bagaimana cara mengedit gambar dengan Ideogram 4.6 API? Panggil ideogram-v4.6-edit dengan satu URL di image_urls dan perubahan yang diinginkan di prompt. Tambahkan edit_precision: high untuk mempertahankan piksel yang tidak Anda minta untuk diubah.

Bisakah saya mengirim gambar referensi ke ideogram-v4.6? Tidak. Di PoYo, referensi dikirim di reference_image_urls pada ideogram-v4.6-edit, hingga 4, atau 3 jika memakai mask.

Berapa banyak gambar yang dikembalikan satu request Ideogram 4.6 API? 1 sampai 8, diatur dengan n. Setiap gambar ditagih sesuai harga tingkatannya.

Mengapa request Ideogram 4.6 API saya ditolak karena ukuran? Sisi kustom harus kelipatan 32 antara 256 dan 4096, dan mask atau edit presisi tinggi membutuhkan size: auto.

Share: