AiWings API reference

The AiWings API is a JSON API over HTTPS. You send requests with an API key, AiWings runs the model, stores the result, and gives you back a permanent URL to the file.

All endpoints live under one base URL:

https://aiwings.io/api/v1

• Requests and responses are JSON. Send Content-Type: application/json with a body.
• Images and videos are jobs: you start one, then read its status until it's done. See How jobs work.
• The API uses the same credits as AiWings in your AI agents. There's no separate plan.

1. Create a key on the API page in your dashboard.
2. Store it as an environment variable, for example AIWINGS_API_KEY.
3. Create an image. With "wait": true the request returns once the image is ready (up to 60 seconds), so you get the URL in one call.

1curl https://aiwings.io/api/v1/images \
2  -H "Authorization: Bearer $AIWINGS_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "prompt": "A ceramic coffee mug on a sunny kitchen counter",
6    "model": "gpt-image-2.5-flare",
7    "quality": "medium",
8    "aspect_ratio": "1:1",
9    "wait": true
10  }'

The response is an image object:

{
  "id": "8f1c2a4e-5b7d-4e2f-9a31-0c6d8e7f1b22",
  "object": "image",
  "status": "succeeded",
  "model": "gpt-image-2.5-flare",
  "quality": "medium",
  "aspect_ratio": "1:1",
  "prompt": "A ceramic coffee mug on a sunny kitchen counter",
  "output": {
    "url": "https://…/generations/8f1c2a4e-5b7d-4e2f-9a31-0c6d8e7f1b22.png"
  },
  "credits": 6,
  "error": null,
  "created_at": "2026-10-31T09:41:12.512Z"
}

Every request needs your API key in the Authorization header, as a Bearer token:

Authorization: Bearer aiw_live_…

• Keys start with aiw_live_ followed by 40 random characters.
• Keys in the URL (for example ?api_key=) are always rejected, so they never end up in logs or browser history.
• A missing, malformed or revoked key returns 401 authentication_failed.
• The API does not allow browser (CORS) requests. Call it from your server, a script, or a backend function, never from front-end or mobile app code where anyone could read the key.

AiWings is built so that a key does as little damage as possible if it ever leaks.

Recommended practice:

• Use one key per app or environment (production, staging, a script), so you can revoke one without touching the others.
• Set a monthly limit on every key, sized to what that app should ever spend.
• Keep keys in environment variables or a secrets manager. Never commit them to git.
• To rotate a key: create a new one, deploy it, then revoke the old one. You can have up to 10 active keys.
• If a key leaks, revoke it right away and email Mejed@templyo.io.

Images take seconds and videos can take minutes, so every generation runs as a job. Creating one returns right away with a job object whose status is one of:

Three ways to get the result:

• Wait on create. Add "wait": true (or a number of seconds, up to 60) to the request body. Best for images.
• Long-poll. Call GET /v1/images/{id}?wait=30 or GET /v1/videos/{id}?wait=30. The request returns as soon as the job finishes, or after 30 seconds with the current status. Best for videos.
• Poll. Call the GET endpoint every few seconds without wait.

Jobs keep running even if your request disconnects. A job started from your code also shows up in your dashboard library.

Networks fail. To retry a create request safely, send an Idempotency-Key header with a unique value (a UUID works well, 1–100 characters of letters, numbers, - _ : .).

If a job with that key already exists on your account, the API returns that job instead of starting a new one, so you're never charged twice. Replayed responses have the header Idempotent-Replayed: true and status 200 instead of 201.

curl -X POST "https://aiwings.io/api/v1/images" \
  -H "Authorization: Bearer $AIWINGS_API_KEY" \
  -H "Idempotency-Key: 9b2f4c1e-sneaker-hero" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Studio photo of a red sneaker",
    "wait": true
  }'

Errors use standard HTTP status codes and always have the same body. Include the request_id when you contact support. Every response also carries it in the X-Request-Id header.

{
  "error": {
    "type": "invalid_request",
    "message": "GPT Image 2.5 Flare quality must be one of: low, medium, high, xhigh, max.",
    "param": "quality",
    "request_id": "req_4c1f0e6a9b2d4e7f8a1b2c3d4e5f6a7b"
  }
}

Unknown fields are rejected rather than ignored, so a typo like "resoltion" fails loudly instead of quietly using a default.

Every response tells you where you stand:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1761903720   # unix seconds when the window resets

On 429, wait for the number of seconds in Retry-After, then retry. Need higher limits? Email Mejed@templyo.io.

• The API draws from the same credit balance as your AI agents and the dashboard.
• Images cost a fixed number of credits per image, by model and quality. Videos cost credits per second, by model and resolution. Jobs with a reference video use a higher per-second rate.
• Credits are charged when a job starts. Failed jobs are refunded automatically.
• Each job returns what it cost in credits. GET /v1/models lists every price and GET /v1/account shows your balance.

Full price tables are under Image models and Video models, and plans are on the credits page.

Generates a new image from a prompt, or edits images: pass reference images (your product, a character, a style) or the id of an earlier image to change it.

Returns 201 with an image object.

Edit with a reference image

curl -X POST "https://aiwings.io/api/v1/images" \
  -H "Authorization: Bearer $AIWINGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Place this bottle on a mossy rock in a misty forest, soft morning light",
    "model": "nano-banana-pro",
    "quality": "2K",
    "aspect_ratio": "4:5",
    "reference_images": [
      "https://example.com/bottle.png"
    ],
    "wait": true
  }'

Change an earlier result

curl -X POST "https://aiwings.io/api/v1/images" \
  -H "Authorization: Bearer $AIWINGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Same scene, but at night with warm string lights",
    "source_generation_id": "8f1c2a4e-5b7d-4e2f-9a31-0c6d8e7f1b22",
    "wait": true
  }'

Returns the current state of an image job. Add ?wait=30 to hold the request until it finishes (max 60).

curl "https://aiwings.io/api/v1/images/8f1c2a4e-5b7d-4e2f-9a31-0c6d8e7f1b22?wait=30" \
  -H "Authorization: Bearer $AIWINGS_API_KEY"

Starts a video job: text to video, animate an image (first frame, optional last frame), or guide the video with reference images and clips. Videos include generated audio unless you turn it off.

1# 1. Start the job
2curl https://aiwings.io/api/v1/videos \
3  -H "Authorization: Bearer $AIWINGS_API_KEY" \
4  -H "Content-Type: application/json" \
5  -H "Idempotency-Key: launch-teaser-001" \
6  -d '{
7    "prompt": "Slow dolly shot of a glass bottle on wet sand at sunset, waves rolling in",
8    "model": "seedance-2.0",
9    "resolution": "720p",
10    "duration": 5,
11    "aspect_ratio": "16:9",
12    "audio": true
13  }'
14 
15# 2. Poll until status is "succeeded" (or "failed")
16curl "https://aiwings.io/api/v1/videos/VIDEO_ID?wait=30" \
17  -H "Authorization: Bearer $AIWINGS_API_KEY"

Returns 201 with a video object:

{
  "id": "2b9e6d10-7c3a-4f8e-b1d2-55a0c9e4f871",
  "object": "video",
  "status": "processing",
  "model": "seedance-2.0",
  "resolution": "720p",
  "duration": 5,
  "aspect_ratio": "16:9",
  "audio": true,
  "format": "mp4",
  "prompt": "Slow dolly shot of a glass bottle on wet sand at sunset",
  "output": null,
  "credits": 115,
  "error": null,
  "created_at": "2026-10-31T09:45:03.020Z"
}

Returns the current state of a video job. Add ?wait=30 to long-poll: the request returns as soon as the video is ready, or after 30 seconds (max 60).

curl "https://aiwings.io/api/v1/videos/2b9e6d10-7c3a-4f8e-b1d2-55a0c9e4f871?wait=30" \
  -H "Authorization: Bearer $AIWINGS_API_KEY"

Your images and videos, newest first, from the API, your AI agents and the dashboard.

{
  "object": "list",
  "data": [
    {
      "id": "8f1c2a4e-5b7d-4e2f-9a31-0c6d8e7f1b22",
      "object": "image",
      "status": "succeeded",
      "model": "gpt-image-2.5-flare",
      "quality": "medium",
      "aspect_ratio": "1:1",
      "prompt": "A ceramic coffee mug on a sunny kitchen counter",
      "output": {
        "url": "https://…/generations/8f1c2a4e-5b7d-4e2f-9a31-0c6d8e7f1b22.png"
      },
      "credits": 6,
      "error": null,
      "created_at": "2026-10-31T09:41:12.512Z"
    },
    "…"
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0xMC0zMVQwOTo0MToxMi41MTJa…"
}

Any single generation, image or video. Supports ?wait like the endpoints above.

For files on your machine or server. Ask for an upload URL, PUT the bytes to it, then pass the returned url anywhere a URL is accepted (reference_images, first_frame, last_frame, reference_videos). Files that are already public on the web can be passed directly.

{
  "id": "upl_6f1d2c3b4a5e6f708192a3b4",
  "object": "upload",
  "filename": "product.png",
  "content_type": "image/png",
  "upload_url": "https://…/object/upload/sign/…?token=…",
  "upload_method": "PUT",
  "upload_headers": {
    "Content-Type": "image/png"
  },
  "url": "https://…/api-uploads/upl_6f1d2c3b4a5e6f708192a3b4.png",
  "expires_at": "2026-10-31T11:41:12.512Z"
}

The upload URL works once and expires after 2 hours. Uploaded files are public but unguessable, like outputs.

1# 1. Ask for an upload URL
2curl https://aiwings.io/api/v1/uploads \
3  -H "Authorization: Bearer $AIWINGS_API_KEY" \
4  -H "Content-Type: application/json" \
5  -d '{ "content_type": "image/png", "filename": "product.png" }'
6 
7# 2. PUT the file to upload_url from the response
8curl -X PUT "UPLOAD_URL" \
9  -H "Content-Type: image/png" \
10  --data-binary @product.png
11 
12# 3. Use the returned "url" as a reference
13curl https://aiwings.io/api/v1/images \
14  -H "Authorization: Bearer $AIWINGS_API_KEY" \
15  -H "Content-Type: application/json" \
16  -d '{ "prompt": "Put this product on a marble table, soft daylight", "reference_images": ["URL"] }'

Every model with its options and credit prices. Filter with ?type=image or ?type=video. Use it to build model pickers or to check prices before you start a job.

{
  "object": "list",
  "data": [
    {
      "id": "nano-banana-2",
      "object": "model",
      "type": "image",
      "name": "Nano Banana 2",
      "description": "Best quality-per-credit (Gemini 3.1 Flash Image)",
      "qualities": [
        {
          "value": "1K",
          "credits": 8
        },
        {
          "value": "2K",
          "credits": 13
        },
        {
          "value": "4K",
          "credits": 19
        }
      ],
      "default_quality": "1K",
      "aspect_ratios": [
        "1:1",
        "2:3",
        "3:2",
        "…"
      ],
      "max_reference_images": 14
    },
    "…"
  ]
}

Defaults are used whenever a request leaves out model, quality, resolution, duration, aspect_ratio or audio. They're shared with your AI agents and the dashboard. PATCH only changes the fields you send.

curl -X PATCH "https://aiwings.io/api/v1/defaults" \
  -H "Authorization: Bearer $AIWINGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "model": "nano-banana-2",
      "quality": "2K"
    },
    "video": {
      "resolution": "1080p",
      "duration": 8
    }
  }'

{
  "object": "defaults",
  "image": {
    "model": "nano-banana-2",
    "quality": "2K"
  },
  "video": {
    "model": "seedance-2.0",
    "resolution": "1080p",
    "duration": 8,
    "aspect_ratio": "16:9",
    "audio": true
  }
}

Your credit balance, plan, and how much this key has spent this month.

{
  "object": "account",
  "credits": 1840,
  "plan": "sub-pro",
  "subscription_status": "active",
  "renews_at": "2026-11-28T00:00:00Z",
  "can_generate": true,
  "api_key": {
    "name": "Shopify sync",
    "monthly_credit_limit": 1000,
    "credits_used_this_month": 212
  }
}

Credits per image. Live values are always in GET /v1/models?type=image.

Credits per second of video. Live values are always in GET /v1/models?type=video.

Example: a 5-second seedance-2.0 video at 720p costs 23 × 5 = 115 credits.