Skip to main content
This guide walks you through the full flow from setting up your account to making your first API call. It takes about 5 minutes.

​
Prerequisites

Before you start, please confirm the following:
1

Create an imini account

Visit imini.ai to register and verify your email.
2

Top up credits

All API calls are billed in credits. See Pricing for each model’s consumption rules. Please top up at Credits before making any calls.
3

Create an API Key

Go to the API Keys management page, create an API Key for server-side use, and store it securely.

​
Base URL

All imini Open Platform endpoints share the same base URL: 
https://openapi.imini.ai/imini/router
The relative paths in the examples below (such as /v1/images/generate) should be appended to this base URL.

​
Authentication

Every request authenticates via an HTTP header using the Bearer Token standard: 
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
API Key security: Only use your API Key on the server side. Never commit it to a code repository, ship it in frontend code or mobile apps, or expose it in any other way. If you suspect a key has leaked, rotate it immediately on the API Keys management page.

​
Asynchronous Task Model

All generation endpoints on imini (image and video) use an asynchronous task model. A complete generation flow is two steps: 
┌──────────────────────────────────────────┐
│ 1. Submit the generation task            │
│    POST /v1/images/generate              │
│    → synchronously returns { task_id }   │
└────────────────┬─────────────────────────┘
                 │
                 ▼
┌──────────────────────────────────────────┐
│ 2. Poll the task status                  │
│    GET  /v1/images/tasks/{task_id}       │
│    → status: queued → processing         │
│             → succeeded (with images[].url) │
│             → failed (with error object) │
└──────────────────────────────────────────┘
The image task query endpoint is /v1/images/tasks/{task_id}; the video task query endpoint is /v1/videos/tasks/{task_id}. A polling interval of 2 seconds is recommended. Image tasks typically complete within 10–30 seconds.

​
Step 1: Submit the Generation Task

The example below uses the google/nano-banana model to generate a 1:1 image: 
curl -X POST https://openapi.imini.ai/imini/router/v1/images/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/nano-banana",
    "prompt": "An orange cat napping under a cherry blossom tree, watercolor style",
    "aspect_ratio": "1:1"
  }'
Successful response (HTTP 200): 
{
  "task_id": "task_2041350318103396352",
  "model": "google/nano-banana",
  "created_at": "2026-04-07T03:00:17.062Z",
  "request_id": "285f20ce-8158-401b-945c-7bc6a7ef6ead"
}

​
Step 2: Poll the Task Result

Use the task_id returned above to poll until status becomes succeeded or failed: 
curl https://openapi.imini.ai/imini/router/v1/images/tasks/TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
Task status values:
StatusMeaning
queuedTask submitted, waiting to enter the processing queue
processingModel is generating
succeededGeneration succeeded, result is in the images[] field
failedGeneration failed, details in the error object
Successful response example (status: succeeded): 
{
  "task_id": "task_2041350318103396352",
  "status": "succeeded",
  "model": "google/nano-banana",
  "created_at": "2026-04-07T03:00:17.062Z",
  "completed_at": "2026-04-07T03:00:29.418Z",
  "images": [
    {
      "url": "https://file.iminicdn.com/file/2026/04/07/xxxx.png",
      "width": 1024,
      "height": 1024
    }
  ],
  "error": null,
  "request_id": "285f20ce-8158-401b-945c-7bc6a7ef6ead"
}

​
Error Handling

All error responses share a unified structure: 
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "aspect_ratio must be one of: 1:1, 2:3, ...",
    "status": 400,
    "request_id": "req_abc123"
  }
}
Common HTTP status codes:
StatusMeaningTypical cause
400Invalid request parametersMissing required field, invalid enum value, or prompt flagged by content safety
401Authentication failedAPI Key missing, invalid, or revoked
402Insufficient creditsAccount balance cannot cover this call
404Resource not foundThe specified task_id does not exist or has expired
429Rate limit exceededExceeded your account’s rate quota; back off and retry
500Internal platform errorPlatform-side issue; please retry later
502Upstream model errorUnderlying model service unavailable; usually safe to retry immediately
Every response includes a request_id. Please include it when submitting tickets or contacting support so we can investigate quickly.

​
Production Integration Tips

Before integrating imini into production, review the following practices:
  • Set reasonable polling intervals: We recommend a first poll at 2 seconds, then exponential backoff (2s / 3s / 5s) to reduce pressure on the query endpoint.
  • Configure sensible timeouts: Use a 30-second timeout for submission calls. Set overall polling timeouts based on the model (e.g., 2 minutes for image, 10 minutes for video).
  • Error retry strategy: For 429, 500, and 502, retry 2–3 times with random jitter. Do not retry 400, 401, or 402.
  • API Key rotation: Store API Keys in a secrets manager (KMS / Secrets Manager), rotate them regularly, and use separate keys per business scenario for observability and isolation.
  • Idempotency and request tracing: Record the submitted task_id and request_id on your side to reconcile against platform logs.
  • Content safety: We recommend pre-screening user-supplied prompts and reference images on your side to reduce the likelihood of triggering 400 content-violation errors.

​
Next Steps

API Reference

Full parameter definitions and an interactive Playground for each model

Pricing

Credit consumption rules by model, resolution, and scenario

Changelog

Track new model launches, parameter changes, and service updates

Terms & Policies

Please read the Terms of Service and Privacy Policy before onboarding