IMAGILD / DEVELOPERS
Build with images and video.
Practical guides for choosing models, controlling point costs and recovering asynchronous media jobs. Start with the contract, then find the exact problem you need to solve.
Start and authenticate
Imagild API: Images and Video Developer Guide
Build an Imagild image and video integration with exact endpoints, model IDs, point costs, secure keys, idempotent submission, polling and downloads.
Why Does My API Key Need Membership and Points?
Separate Imagild API membership, valid keys and points. Diagnose access failures and budget image or video tasks without paying for the wrong fix.
Which Base URL Should My Imagild Client Use?
Set the Imagild API base URL, join relative routes correctly, and diagnose duplicated version prefixes or HTML responses before changing credentials.
Make Your First Image API Request with curl
Submit a 1K Imagild image with curl, preserve its operation ID, poll the saved task, and verify authenticated media downloads and point usage.
Separate Development and Production API Keys
Use separate Imagild keys for development and production, protect secrets, plan a safe deployment cutover and avoid assuming separate billing pools.
Prevent Expired API Keys from Breaking Media Jobs
Track Imagild key expiry, plan 30- or 90-day rotations within the five-key limit, and resume existing media tasks with replacement credentials.
What Should I Do After Exposing an API Key?
Contain an exposed Imagild API key, replace it safely, review affected operations and reconcile accepted tasks without assuming revocation cancels them.
Why Can a Finished API Result Still Return 403?
Diagnose a membership-related 403 on a completed Imagild task, distinguish access from billing, and recover owned downloads without regenerating media.
Hand Off an API Integration Without Sharing Secrets
Prepare a sanitized Imagild API handoff with environment settings, task examples, cost boundaries and recovery steps while keeping credentials private.
Image requests and models
Which Image Model IDs Does Imagild Expose?
Discover Imagild’s three canonical image model IDs, read the live catalog, and build a selector that preserves each task’s model and point quote.
Why Does My Image Request Reject Extra Fields?
Fix rejected Imagild image requests with the exact allowed JSON fields, a local preflight check, and clear handling of unsupported image settings.
Choose 1K, 2K or 4K Before an API Image Request
Compare Imagild’s 10, 15 and 20-point image tiers, budget drafts and retakes, and choose a resolution using concrete delivery requirements.
Can I Generate an API Image Without Uploading One?
Generate an Imagild image from a prompt alone with a minimal text-only request, then track the asynchronous task and verify its downloaded result.
Should I Send file_id or image_task_id?
Choose the correct Imagild API image reference selector for an uploaded photo or a completed generated image, with ownership and validation checks.
Why Does a Reference-Image Prompt Fail Validation?
Fix Imagild’s 20-character reference prompt requirement with a trimmed-length preflight, source checks, and clear editable instruction examples.
How Do I Request Several Images Without an n Field?
Build an Imagild image batch from separate operations, with a durable manifest, explicit points budget, stable retry keys, and partial-result recovery.
Verify Image Dimensions Before Publishing API Output
Check Imagild output bytes, format and decoded dimensions before publishing, with a Pillow example and an acceptance manifest tied to the task.
Switch Image Models Without Losing Existing Jobs
Keep Imagild jobs intact when users switch models: separate draft state, create new operation keys deliberately, and poll each original task ID.
Video requests and references
Generate a Short Video from an API Text Prompt
Submit a short H3 video request with valid duration, resolution and aspect ratio, then poll the task and download its authenticated result.
Turn a Completed API Image into a Video
Reuse a successful image task as a video reference, preserve both task IDs and budget correctly for the separate image and motion generations.
Use an Uploaded Photo in a Video API Request
Upload a photo with the correct multipart field, bind its returned file ID to a video request and check reference ownership before reviewing motion.
First Frame or Reference Image: Which Video Role?
Choose an opening-frame or general-image-reference role deliberately, then compare motion and preserved details with separate video tasks.
Validate Video Aspect Ratios Before Submission
Check a video model’s supported ratios before submission and separate the generated file’s orientation from the website player’s crop.
Choose 768P or 2K for API Video
Compare 768P and 2K video budgets, inspect the delivered file and decide whether a higher-resolution retake addresses the actual defect.
When Should I Enable H3 Enhancement in the API?
Budget the five-point H3 enhancement option, send context_ir correctly and evaluate paired clips without assuming a universal quality improvement.
Why Is My 30-Second Video API Request Rejected?
Diagnose the 4–15-second API duration limit, reject invalid values clearly and budget separate clips without promising native long-film generation.
Build a Longer Film from Short API Clips
Plan multiple short API clips with an application timeline manifest, resolve image dependencies and inspect continuity during external film assembly.
Async task lifecycle
Does HTTP 202 Mean My Image Is Ready?
Understand why Imagild HTTP 202 confirms acceptance rather than completion, then map task status, usage state and output checks to a truthful user interface.
Poll Media Tasks Without Resubmitting Generation
Build a bounded Imagild task poller that honors poll_after_seconds, handles rate limits and preserves task identity without resubmitting paid generation.
My Poller Timed Out: Did the Media Task Fail?
Separate a local polling deadline from an Imagild task failure, preserve operation identity and resume status checks without buying duplicate media.
Resume a Media Task After Refreshing the Page
Restore Imagild task cards after a browser refresh using durable operation records, owner-scoped reads and UI hydration that never resubmits work.
Recover Submitted Jobs After Your App Restarts
Recover accepted Imagild media jobs after an app restart with persistent operation records, coordinated reconciliation and safe idempotency recovery.
Why Does a Failed Generation Return HTTP 200?
Handle HTTP 200 task records that contain failed generation states, distinguish request errors and inspect usage before rendering or retrying output.
What Does an Unknown Video Task State Mean?
Handle an unknown Imagild video outcome conservatively, preserve the accepted operation and prepare sanitized evidence without automatic paid retries.
Why Is output_url Empty After Submission?
Diagnose an empty Imagild output_url using task state, validate the private content route and distinguish unfinished generation from display problems.
Does Aborting fetch Cancel My AI Generation?
Understand why aborting fetch does not cancel accepted Imagild generation, retain task identity and implement honest stop-waiting behavior in your app.
Safe retries and idempotency
Design Idempotency Keys for Paid Media Operations
Choose stable Imagild operation keys, preserve approved request snapshots, and distinguish safe retry identity from a deliberately new paid generation.
Retry a Media Submission After a Network Disconnect
Recover an interrupted Imagild submission using the original request and key, then resume the saved task instead of creating another paid generation.
Stop Double Clicks from Creating Two Paid Images
Pair a stable backend operation with clear button states so repeated clicks recover the existing Imagild task instead of authorizing duplicate paid images.
Why Does Reusing My Idempotency Key Return 409?
Diagnose Imagild idempotency conflicts by comparing the original parsed request with a changed prompt, model, resolution, reference, or endpoint.
Handle Concurrent Retries of One Generation Request
Coordinate concurrent Imagild workers with a durable unique operation record, saved remote key, and crash recovery instead of relying on process locks.
When Does an Image Variation Need a New Key?
Decide whether a user wants an existing Imagild task or a new image candidate, including identical prompts, model changes, references, and resolution upgrades.
What If Submission Returns 500 but Work May Exist?
Investigate an ambiguous media submission error without losing operation identity, confusing transport status with task outcome, or triggering duplicate spend.
Where Should I Store Media Idempotency Keys?
Store Imagild operation keys with immutable request snapshots, account ownership, fingerprints and task IDs so restarts preserve recovery evidence.
Can I Retry an Image Upload with Idempotency-Key?
Separate Imagild upload resources from generation idempotency, save returned file IDs, and avoid changing a reference during uncertain task recovery.
Limits and queue design
Handle 429 Responses Without a Retry Storm
Respect Imagild 429 retry delays, coordinate a shared cooldown and preserve operation identity so throttling does not trigger duplicate generations.
Do Multiple API Keys Increase My Rate Limit?
Coordinate multiple Imagild keys under one account rate budget, allocate read and write headroom and separate quotas from points and throughput.
Build a Bounded Worker Pool for Media Requests
Bound media submission concurrency, combine it with account pacing and recover individual operations without holding workers until generation completes.
Poll Many Tasks Within a Shared Read Budget
Calculate a shared task-polling budget, stagger checks and reserve reads for downloads without creating overlapping timers or invented completion times.
Share the Write Budget Between Uploads and Renders
Count reference uploads and media submissions in one write budget, save source dependencies and retry uploads separately from idempotent generations.
Keep a Stuck Video from Blocking Your Entire Queue
Defer a slow video without blocking independent media work, preserve its task and billing evidence and avoid treating local timeouts as cancellation.
Show Useful Progress Without Inventing Percentages
Design accurate media-task progress with real states, stale-read labels and indeterminate indicators instead of unsupported percentages or queue positions.
Schedule Daily Media Jobs Without Burst Traffic
Plan recurring media jobs with explicit dates, durable operation keys and paced catch-up runs, then review results independently of the publication clock.
Test Rate-Limit Handling Without Buying Images
Use local 429 fixtures and a controlled clock to test retry timing, queue recovery and unchanged operation keys without paying for media or flooding production.
Prices and point accounting
Calculate Image API Costs from Points and Packs
Convert Imagild image points into pack-based USD values, compare 1K, 2K and 4K budgets and keep membership, retakes and upfront purchases separate.
Budget H3 Video Tasks Before You Submit
Calculate H3 video points from duration, resolution and enhancement, then add a source image and one approved retake without hiding membership costs.
What Do Reserved, Consumed and Released Points Mean?
Understand Imagild reserved, consumed, released and not-reserved usage states, and display task costs without double-counting reads or cash refunds.
When Does a Failed API Task Release Its Points?
Check confirmed task failure and point release, distinguish unknown outcomes and prepare safe reconciliation evidence without promising refund timing.
Check a Media Budget Before Spending Points
Estimate an Imagild image or video plan before submission, account for shared-wallet races and handle server reservation rejection without overspending.
Will a Pricing Change Reprice My Submitted Task?
Preserve a submitted Imagild task's own usage quote when catalog prices change, and separate historical task costs from new-operation estimates.
Add a Daily Spend Cap to Your Media App
Enforce a daily point cap in your own media app using transactional allowances, stable operations and unresolved commitments instead of API flags.
Reconcile Batch Costs with Per-Task API Usage
Join your batch manifest to unique Imagild task usage, separate consumed and reserved points and expose missing receipts instead of hiding uncertainty.
Use 1K Previews Before 4K Final API Images
Compare 1K-preview and 4K-final budgets with acceptance-rate math, separate each paid generation and verify final images without promising free upgrades.
Upload and deliver files
Upload a Reference Photo with Multipart Form Data
Upload an Imagild reference using multipart photo data, keep keys on the backend, preserve FormData boundaries, and save file_id before generation.
Why Is My API Reference File Not Found?
Diagnose missing Imagild reference files by checking upload acknowledgments, account ownership, hidden selector state, and source availability.
Preview a Private API Image in a Browser
Display private Imagild images through an authorized app route, create controlled Blob previews, and release object URLs without exposing the API key.
Play a Private API Video Without Leaking the Key
Stream private Imagild videos through an authorized app route that preserves Range responses, avoids full buffering, and keeps upstream keys server-side.
Resume an Interrupted API Result Download
Recover Imagild media downloads with a single byte range, validate 206 and Content-Range, and handle 200 or 416 without corrupting partial files.
Why Did My Image Download Save JSON Instead?
Distinguish task JSON and API errors from image content, then validate status, MIME type, signature and decoding before publishing downloaded media.
Archive API Outputs in Your Own Object Storage
Archive approved Imagild outputs with a recoverable manifest, streaming checksum, verified stored copy and deliberate access and retention policies.
Set Safe Download Filenames for Generated Media
Give Imagild result downloads safe application-owned filenames using validated MIME extensions and controlled Content-Disposition headers.
Security and ownership
Keep AI API Keys Out of Frontend Bundles
Keep Imagild keys on the backend, authorize application users before forwarding and inspect built assets, logs and error paths for accidental disclosure.
Prevent Users from Reading Another Tenant's Media
Map application users to permitted remote media tasks and apply ownership checks to status, previews, downloads and exports under a shared service account.
Log AI Failures Without Recording Keys or Photos
Build allowlisted media-failure logs that retain task and request correlation without copying API keys, private prompts or source photographs.
Secure Your App's Reference-Photo Upload Route
Bound your app’s reference-photo upload route, distinguish local and API limits and bind validated uploads to authorized users before generation.
Why Should API Tokens Never Go in Media URLs?
Keep Bearer tokens out of media URLs and build owner-aware backend delivery routes that preserve authentication without exposing account credentials.
Does Enabling CORS Make an API Integration Secure?
Separate browser CORS settings from user authentication, media ownership and spending checks when integrating an AI API through your backend.
Treat Prompts as Data in Your Media Backend
Keep media prompts as creative data while your backend controls permitted fields, reference ownership, credentials and fixed network destinations.
Export a User's Media Records Without Crossing Accounts
Export user-authorized media through an application manifest, handle partial downloads and protect archive access without inventing a bulk-export endpoint.
Does Revoking an API Key Delete Generated Media?
Distinguish API key revocation from task cancellation, stored-media deletion and removal of application copies, with verifiable lifecycle effects.
Backend integration
Submit AI Jobs from a Next.js Server Route
Build a Next.js server boundary for paid Imagild jobs, persist approved operations and outbox events, protect secrets and return before generation finishes.
Why Does My Next.js Poller Keep Showing Old Status?
Diagnose stale Imagild task status in Next.js with explicit no-store reads, private proxy responses and separate checks for browser and server caching.
Run AI Generation from Short-Lived Serverless Routes
Design serverless media submission around durable operations, short reconciliation visits and recovery across shutdowns instead of long polling requests.
Write a Python Poller with Separate HTTP and Job Timeouts
Use HTTPX with separate request timeouts and a bounded Python polling budget, preserving Imagild task identity when local waiting or connections stop.
Stream API Media Through Node Without Full Buffering
Proxy private Imagild media through Node streams, preserve single-range responses and stop disconnected transfers without buffering complete video files.
Keep FastAPI Media Jobs Alive Across Process Restarts
Separate FastAPI request handling from durable paid media work, store outbox events and recover Imagild operations after process or worker restarts.
Model Paid AI Operations in Django Transactions
Design Django operation records with unique intent, frozen requests and an outbox, keeping paid Imagild submission outside open database transactions.
Use Go Context Timeouts Without Losing Remote Tasks
Apply Go context deadlines to Imagild HTTP reads while preserving remote task identity, handling interrupted submissions and resuming owned operations.
Configure Laravel Queue Retries for Paid Media Work
Align Laravel HTTP, worker and queue retry limits around persisted Imagild operations, avoiding new paid generation identities on duplicate deliveries.
Product workflows and UX
Build an n8n Image API Workflow with Status Branches
Integrate Imagild with n8n HTTP Request, Wait and Switch nodes while preserving operation identity, branching task outcomes and avoiding duplicate spend.
Add Your Own Completion Callback with a Polling Worker
Build an application-owned completion callback around Imagild polling, using durable events, separate HMAC secrets, receiver validation and duplicate handling.
Build a React Progress Card for Async Media Tasks
Build a truthful React task card with stable operation identity, stale-response guards, resumable polling, and separate task, transport and waiting states.
Schedule an Image-to-Video Dependency Graph
Schedule Imagild image-to-video stages with durable dependencies, approved sources, per-node task identity, bounded budgets and targeted failure recovery.
Let Users Download Successful Items from a Partial Batch
Design partial-batch Imagild results with per-item downloads, honest usage summaries, and targeted recovery that preserves already successful media.
Require Human Image Approval Before Generating Video
Add an application approval gate tied to an exact completed image and video quote, so source success never silently authorizes new video spend.
Version Prompt Templates Without Mutating Running Jobs
Keep Imagild prompt-template provenance separate from immutable request snapshots, so edits and retries preserve task identity and approved spending.
Create a Safe Support Packet for a Stuck API Task
Prepare an Imagild support summary with task identity, timestamps, usage and sanitized diagnostics while keeping credentials and customer media private.
Quality and operations
Test Your AI API Client with Recorded Contract Fixtures
Build versioned media-client fixtures for acceptance, task states and authenticated output, while separating local contract evidence from real generation.
Test Network Failures Without Duplicating Paid Tasks
Inject local connection and crash failures around acceptance, preserve operation identities and recover downloads without duplicating paid generations.
Verify Text in API-Generated Images Before Delivery
Proofread generated image text against approved copy, inspect the final crop and use optional external OCR without treating it as a spelling guarantee.
Check Whether a Video Actually Uses the Intended Image
Trace a video to its approved reference image and review the chosen role, complete motion and soundtrack before accepting the downloaded clip.
Measure Your Media Integration's Reliability Honestly
Measure transport, task, media and review outcomes separately, preserve unresolved jobs and define honest denominators for your integration dashboard.
Detect Model or Resolution Changes Before They Break Jobs
Compare validated model catalog snapshots semantically, identify affected drafts and preserve accepted jobs when capabilities or point quotes change.
Separate Mock Integration Tests from Paid Model Checks
Separate local fixtures, authenticated reads and approved paid model checks, with a point ceiling and evidence labels that do not imply a free sandbox.
Release a Media Client with a Safe Rollback Plan
Preserve task records through a media-client release, canary the read path first and rehearse rollback without resubmitting accepted operations.
Compare Image APIs Beyond the Headline Price
Compare image APIs using accepted outputs, access costs, request limits and retakes rather than unsupported cheapest-price or availability claims.