AI image API: a glowing eight-pointed star linked by lines of light to four glass panels, on a dark Islamic star pattern
Guides • 7 min read

AI Image API: How to Add AI Pictures and Videos to Your Own App

You can add AI pictures and videos to your own app with a few HTTP calls to the HalalGen AI image API. Make a key on the API keys page, send your prompt to POST /v1/generate, then ask GET /v1/prompts/{id} for the finished picture. Below is every step with code you can copy, what each call costs, and how to keep your key safe.

Building picture features on your own usually means signing up with several model companies, juggling their keys and prices, and hoping nothing slips into your product that your customers wouldn't want to see. With HalalGen you use one key and one balance of tokens, and every prompt is checked against our content rules before a model sees it.

In this guide
  • Your key: make one and keep it out of your code.
  • Your first picture and video: one request each, with code in cURL, JavaScript and Python.
  • Your rules: what a key can do, where it works and how much it can spend.
2 tokens
A picture
With HalalGen Standard, the API's default model
46 tokens
A 5-second video
Seedance 2.5 at 720p
0 tokens
A failed job
Its tokens go back to your balance

What do you need before you start?

  • A HalalGen account: reading the model list, your balance and your jobs works on any account.
  • A paid plan to make things: pictures, videos and tools through the API need one. Amanah is $10 a month and comes with 300 tokens.
  • A place to run code: a terminal with cURL, or Node.js or Python on your server.

Step 1: Make an API key

Open the API keys page and press Make key. HalalGen asks you to confirm it's you, then shows the key once. It starts with sk-, so copy it straight away.

A new key starts with safe rules: it makes pictures and uses tools but not videos, it can spend 1,000 tokens a day, it ends 90 days from now, and it pauses itself if it's used far more than usual. You can change all of them. If your app makes videos, tick Videos too.

Keep the key out of your code. Save it as a setting on the computer your code runs on:

# macOS or Linux
export HALALGEN_API_KEY="sk-…"

# Windows (PowerShell)
$env:HALALGEN_API_KEY = "sk-…"

Never put a key in a website or in an app people download. Anyone who finds it can spend your tokens.

Step 2: Send a prompt to the AI image API

One POST request starts a picture job. Leave out model and you get HalalGen Standard, at 2 tokens a picture. The answer comes back straight away with the job's id and its price.

HalalGen API • HalalGen Standard picture 16:9

"A lantern-lit courtyard at dusk, blue mosaic tiles, a fountain, no people"

cURL

curl -X POST https://api.halalgen.ai/v1/generate \
  -H "Authorization: Bearer $HALALGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A lantern-lit courtyard at dusk, blue mosaic tiles, a fountain, no people",
    "aspect_ratio": "16:9"
  }'

JavaScript (Node.js 18 or newer, in a .mjs file)

const res = await fetch("https://api.halalgen.ai/v1/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HALALGEN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "A lantern-lit courtyard at dusk, blue mosaic tiles, a fountain, no people",
    aspect_ratio: "16:9",
  }),
});
const job = await res.json();
console.log(job.id, job.cost);

Python (run pip install requests first)

import os, requests

job = requests.post(
    "https://api.halalgen.ai/v1/generate",
    headers={"Authorization": f"Bearer {os.environ['HALALGEN_API_KEY']}"},
    json={
        "prompt": "A lantern-lit courtyard at dusk, blue mosaic tiles, a fountain, no people",
        "aspect_ratio": "16:9",
    },
).json()
print(job["id"], job["cost"])

Example answer:

{
  "id": "a3f9c2e1",
  "object": "image",
  "model": "halalgen-standard",
  "status": "processing",
  "cost": 2
}

A few settings worth knowing:

  • model: any id from GET /v1/models, if you want a different model.
  • aspect_ratio: 1:1, 4:5, 5:4, 9:16, 16:9, 4:3, 3:4, 3:2, 2:3, 21:9 or 9:21.
  • num_images: 1 to 4 pictures in one job.
  • is_private: pictures made through the API stay out of the public gallery unless you send false, or turn that default off in Security and privacy.

Step 3: Get the finished picture

Ask for the job until its status is completed. Asking is free, and a job that fails gives its tokens back.

curl https://api.halalgen.ai/v1/prompts/JOB_ID \
  -H "Authorization: Bearer $HALALGEN_API_KEY"

# Run it again every few seconds until "status" is "completed".

When it's done, images holds the picture links:

{
  "id": "a3f9c2e1",
  "status": "completed",
  "images": [
    "https://api.halalgen.ai/image/generated/….png"
  ],
  "error": null
}
AI image API example result: a lantern-lit courtyard at dusk with blue mosaic tiles, a fountain and glowing lanterns, no people

Example result: the prompt above with HalalGen Standard (GPT Image 2.5 Flare) at 16:9 and standard quality, for 2 tokens. It was made on 22 Nov 2026 in HalalGen's Image Studio, with the same model and prompt the API call uses.

How do I make a video with the API?

Videos work the same way, with two endpoints of their own. First tick Videos on your key: a new key doesn't make videos until you allow it.

curl -X POST https://api.halalgen.ai/v1/video/generate \
  -H "Authorization: Bearer $HALALGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A paper boat drifts down a rainy street at dusk",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

A 5-second video at 720p with Seedance 2.5, the default video model, costs 46 tokens. Videos take a few minutes. Ask GET /v1/video/{id} until the status is completed, then download the file from video_url.

How do I keep my API key safe?

Each key can carry its own rules. They're checked before a job starts, and every answer has a Server-Timing header that shows how long the checks took.

  • What it can do: pictures, videos, tools, or nothing but reading. Anything else answers 403 action_not_allowed.
  • Where it works from: a list of up to 50 IP addresses or ranges, and for keys used in a browser, a list of websites.
  • How much it can spend: calls a day and tokens a day, counted from midnight to midnight UTC.
  • A pause on unusual use: a key used far more than usual pauses itself and emails you.
  • Rolling: get a new secret while the old one keeps working for 1 hour, 24 hours or 7 days, so you can switch without downtime.

The Security and privacy page gives your keys a checkup and lists what to fix. Its audit log shows every change to your keys and settings.

What happens to the prompts you send?

Every word you send goes through our check for Islamic guidelines before a model sees it. The check reads the words: it doesn't look at the finished picture. If the check can't run, the job is refused and costs nothing.

Your prompts are kept for 30 days by default, so you can see them in Analytics → Requests. You can change that to 7 days, 1 day or not at all, or hide them from the list.

Frequently Asked Questions

Can I try the API on the free plan?

You can make a key and read the model list, your balance and your jobs. Making pictures, videos and tools through the API needs a paid plan. Amanah is $10 a month.

Can I call the API straight from my website?

Not with a key inside the page, because anyone could copy it. Call the API from your server. If a key really has to run in a browser, limit it to your website's address and a small number of tokens a day.

Are the finished pictures checked as well?

No. The check reads the words you send, before anything is made. It doesn't look at results, so look over what you show your own users.

What happens if a job fails or my key hits its limit?

A failed job gives its tokens back. A key that has used up its calls or tokens for the day gets a 429 answer with a Retry-After header, and nothing is charged.

Can I use HalalGen in Claude or ChatGPT without writing code?

Yes. Connect HalalGen as an AI app and ask for pictures in plain words. Our guide to using Claude Opus 5.5 with HalalGen shows how.

That's the whole loop: make a key, send a prompt, collect the result. Start with one 2-token picture, then add the rules your app needs. Building something bigger? See how to build custom agents with HalalGen and how game teams use the API for prototypes.

HalalGen API

Make your first picture through the API

2 tokens a picture with HalalGen Standard. Prompts are checked before generation, and a failed job gives its tokens back.

Open the Quick start ↗