# Api18.dev — Full API reference (LLM-ready)

You are integrating with Api18.dev, an UNCENSORED REST API for AI image and video generation. It applies no content moderation to prompts and permits adult/+18/NSFW use (illegal content is prohibited). Use ONLY the endpoints, parameters and model ids documented below. Do not invent parameters. All requests are JSON over HTTPS.

Billing: pay-as-you-go in USD per call; failed calls are refunded automatically. New accounts get $10 welcome credit usable in the dashboard playground; the API itself requires paid balance, topped up in USDT on the Solana or Tron network (no card required).

## 1. Base URL

    https://api18.dev

## 2. Authentication

Every request needs a Bearer API key in the Authorization header:

    Authorization: Bearer api18_xxxxxxxxxxxxxxxx

Create and copy a key from the dashboard at https://api18.dev/dashboard/api-keys. Keys look like `api18_` followed by 16 alphanumeric characters. Keep them secret (server-side only).

## 3. Easiest way: one call, no polling

Use the single endpoint `POST /v1/generate?wait=true`. It routes by the `model` field and waits for the result, returning the finished job with the output URL in `data[0].url`. This is the recommended path — you write ONE request, no polling loop.

    POST /v1/generate?wait=true   →  routes by `model`, waits, returns the finished job

## 4. How generation works (async + polling)

If you omit `?wait=true` (or the job takes longer than the wait budget), generation is async:
1. POST your request. You get a job with `status` `processing` (or `completed` if instant).
2. Poll `GET /v1/jobs/{id}` every 2–5s until `status` is `completed` or `failed`.
3. When `completed`, `data[].url` holds the output(s). Files are kept for a limited time.
4. Cost is charged in USD when the job is accepted. Failed jobs are refunded automatically.

Endpoints:
- `POST /v1/generate` — any model (routes by `model`). Add `?wait=true` for sync mode.
- `POST /v1/video/generations` — video models (also accepts `?wait=true`)
- `POST /v1/images/generations` — image models (also accepts `?wait=true`)
- `GET  /v1/jobs/{id}` — fetch a job's current status
- `GET  /v1/files/{id}` — 302-redirects to the (first) output file; add `?n=1` for more

## 5. Job response shape

Every POST and `GET /v1/jobs/{id}` returns this JSON:

    {
      "id": "abc123…",
      "object": "generation",
      "model": "<model-id>",
      "output_kind": "video" | "image",
      "status": "processing" | "completed" | "failed",
      "created_at": "ISO-8601",
      "started_at": "ISO-8601 | null",
      "completed_at": "ISO-8601 | null",
      "expires_at": "ISO-8601",
      "retention_days": 7,
      "error": "string | null",
      "cost_usd": 0.30,
      "input": { /* echo of your request */ },
      "timings": { "inference_ms": 1234 },
      "urls": { "get": "https://api18.dev/v1/jobs/{id}" },
      "data": [ { "url": "https://api18.dev/v1/files/{id}" } ]
    }

## 6. Models

### Centaurus 1.0 — Text to Video

- Model id: `centaurus-1.0-text-to-video`
- Family: Centaurus 1.0
- Endpoint: POST /v1/video/generations
- Output: video
- Pricing: $0.20/s @ 720p · $0.30/s @ 1080p (× duration)
- Cinematic text-to-video with crisp detail, stable motion and strong instruction-following. 720p/1080p, multiple aspect ratios, 2–15s clips.

Parameters:
- `model` · string · REQUIRED — The model id. Options: "centaurus-1.0-text-to-video".
- `prompt` · string · REQUIRED — What to generate. Max 2500 characters.
- `resolution` · string · optional — Output resolution. Options: 720p, 1080p. Default: 720p.
- `aspect_ratio` · string · optional — Frame shape. Options: 16:9, 9:16, 1:1, 4:3, 3:4. Default: 16:9.
- `duration` · integer · optional — Clip length in seconds. Options: 2–15. Default: 5.
- `seed` · integer · optional — Reproducible results. Omit for a random seed.
- `negative_prompt` · string · optional — Things to avoid in the output.
- `enable_prompt_expansion` · boolean · optional — Auto-expand a short prompt into a richer script. Default: false.

Example request body:

    {
      "model": "centaurus-1.0-text-to-video",
      "prompt": "A cinematic shot of a city street at night, neon reflections on wet pavement, slow dolly-in",
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "duration": 5
    }

curl:

    curl -X POST https://api18.dev/v1/video/generations \
      -H "Authorization: Bearer $API18_KEY" \
      -H "Content-Type: application/json" \
      -d '{"model":"centaurus-1.0-text-to-video","prompt":"A cinematic shot of a city street at night, neon reflections on wet pavement, slow dolly-in","resolution":"720p","aspect_ratio":"16:9","duration":5}'

### Centaurus 1.0 — Image to Video

- Model id: `centaurus-1.0-image-to-video`
- Family: Centaurus 1.0
- Endpoint: POST /v1/video/generations
- Output: video
- Pricing: $0.28/s @ 720p · $0.56/s @ 1080p (× duration)
- Animate a reference image into a cinematic clip. Aspect ratio matches the source. 720p/1080p, 3–15s.

Parameters:
- `model` · string · REQUIRED — The model id. Options: "centaurus-1.0-image-to-video".
- `image` · string (URL) · REQUIRED — Public URL of the reference image to animate. JPEG/PNG/WEBP/BMP, max 10MB.
- `prompt` · string · REQUIRED — What to generate. Max 2500 characters.
- `resolution` · string · optional — Output resolution. Options: 720p, 1080p. Default: 720p.
- `duration` · integer · optional — Clip length in seconds. Options: 3–15. Default: 5.
- `seed` · integer · optional — Reproducible results. Omit for a random seed.

Example request body:

    {
      "model": "centaurus-1.0-image-to-video",
      "image": "https://example.com/your-image.jpg",
      "prompt": "Gentle camera push-in, hair and fabric moving softly in the breeze",
      "resolution": "720p",
      "duration": 5
    }

curl:

    curl -X POST https://api18.dev/v1/video/generations \
      -H "Authorization: Bearer $API18_KEY" \
      -H "Content-Type: application/json" \
      -d '{"model":"centaurus-1.0-image-to-video","image":"https://example.com/your-image.jpg","prompt":"Gentle camera push-in, hair and fabric moving softly in the breeze","resolution":"720p","duration":5}'

### Hera 1.0 — Image to Video

- Model id: `hera-1.0-image-to-video`
- Family: Hera 1.0
- Endpoint: POST /v1/video/generations
- Output: video
- Pricing: $0.20/s @ 720p · $0.30/s @ 1080p (× duration)
- Cinematic image-to-video with multi-shot narrative support. 720p/1080p, 5/10/15s clips.

Parameters:
- `model` · string · REQUIRED — The model id. Options: "hera-1.0-image-to-video".
- `image` · string (URL) · REQUIRED — Public URL of the reference image to animate. JPEG/PNG/WEBP/BMP, max 10MB.
- `prompt` · string · REQUIRED — What to generate. Max 2500 characters.
- `resolution` · string · optional — Output resolution. Options: 720p, 1080p. Default: 720p.
- `duration` · integer · optional — Clip length in seconds. Options: 5, 10, 15. Default: 5.
- `seed` · integer · optional — Reproducible results. Omit for a random seed.
- `negative_prompt` · string · optional — Things to avoid in the output.
- `shot_type` · string · optional — Single continuous shot or a multi-shot edit. Options: single, multi.
- `enable_prompt_expansion` · boolean · optional — Auto-expand a short prompt into a richer script. Default: false.

Example request body:

    {
      "model": "hera-1.0-image-to-video",
      "image": "https://example.com/your-image.jpg",
      "prompt": "Gentle camera push-in, hair and fabric moving softly in the breeze",
      "resolution": "720p",
      "duration": 5
    }

curl:

    curl -X POST https://api18.dev/v1/video/generations \
      -H "Authorization: Bearer $API18_KEY" \
      -H "Content-Type: application/json" \
      -d '{"model":"hera-1.0-image-to-video","image":"https://example.com/your-image.jpg","prompt":"Gentle camera push-in, hair and fabric moving softly in the breeze","resolution":"720p","duration":5}'

### Hera 1.0 — Image Edit

- Model id: `hera-1.0-image-edit`
- Family: Hera 1.0
- Endpoint: POST /v1/images/generations
- Output: image
- Pricing: $0.070 / run
- Prompt-driven image editing. Upload 1–3 reference images and describe the change.

Parameters:
- `model` · string · REQUIRED — The model id. Options: "hera-1.0-image-edit".
- `prompt` · string · REQUIRED — What to generate. Max 2500 characters.
- `images` · string[] (URLs) · REQUIRED — Array of 1–3 public image URLs to edit. JPEG/PNG/WEBP/BMP, max 10MB each.
- `seed` · integer · optional — Reproducible results. Omit for a random seed.
- `negative_prompt` · string · optional — Things to avoid in the output.
- `enable_prompt_expansion` · boolean · optional — Auto-expand a short prompt into a richer instruction. Default: false.

Example request body:

    {
      "model": "hera-1.0-image-edit",
      "prompt": "Replace the background with a sunny beach, keep the subject unchanged",
      "images": [
        "https://example.com/photo.jpg"
      ]
    }

curl:

    curl -X POST https://api18.dev/v1/images/generations \
      -H "Authorization: Bearer $API18_KEY" \
      -H "Content-Type: application/json" \
      -d '{"model":"hera-1.0-image-edit","prompt":"Replace the background with a sunny beach, keep the subject unchanged","images":["https://example.com/photo.jpg"]}'

### Hera 1.0 — Text to Image

- Model id: `hera-1.0-text-to-image`
- Family: Hera 1.0
- Endpoint: POST /v1/images/generations
- Output: image
- Pricing: $0.056 / image (× num_images)
- Multi-modal text-to-image. 1k/2k resolutions, 9 aspect ratios, generate up to 9 images per call.

Parameters:
- `model` · string · REQUIRED — The model id. Options: "hera-1.0-text-to-image".
- `prompt` · string · REQUIRED — What to generate. Max 2500 characters.
- `aspect_ratio` · string · optional — Image shape. Options: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, auto. Default: 1:1.
- `resolution` · string · optional — Image detail. Options: 1k, 2k. Default: 1k.
- `num_images` · integer · optional — How many images to generate. Options: 1–9. Default: 1.

Example request body:

    {
      "model": "hera-1.0-text-to-image",
      "prompt": "A studio product photo of a ceramic coffee mug on marble, soft light",
      "aspect_ratio": "1:1",
      "resolution": "1k",
      "num_images": 1
    }

curl:

    curl -X POST https://api18.dev/v1/images/generations \
      -H "Authorization: Bearer $API18_KEY" \
      -H "Content-Type: application/json" \
      -d '{"model":"hera-1.0-text-to-image","prompt":"A studio product photo of a ceramic coffee mug on marble, soft light","aspect_ratio":"1:1","resolution":"1k","num_images":1}'

### Zeus 1.0 — Image to Video

- Model id: `zeus-1.0-image-to-video`
- Family: Zeus 1.0
- Endpoint: POST /v1/video/generations
- Output: video
- Pricing: $0.30 (480p, 5s) · $0.48 (480p, 8s) · $0.60 (720p, 5s) · $0.96 (720p, 8s) / run
- Turn an image into a high-quality video with smooth motion. 480p/720p, 5s or 8s clips.

Parameters:
- `model` · string · REQUIRED — The model id. Options: "zeus-1.0-image-to-video".
- `image` · string (URL) · REQUIRED — Public URL of the reference image to animate. JPEG/PNG/WEBP/BMP, max 10MB.
- `prompt` · string · REQUIRED — What to generate. Max 2500 characters.
- `resolution` · string · optional — Output resolution. Options: 480p, 720p. Default: 480p.
- `duration` · integer · optional — Clip length in seconds. Options: 5, 8. Default: 5.
- `seed` · integer · optional — Reproducible results. -1 (or omit) for random. Default: -1.

Example request body:

    {
      "model": "zeus-1.0-image-to-video",
      "image": "https://example.com/your-image.jpg",
      "prompt": "Subtle natural motion, cinematic lighting",
      "resolution": "480p",
      "duration": 5
    }

curl:

    curl -X POST https://api18.dev/v1/video/generations \
      -H "Authorization: Bearer $API18_KEY" \
      -H "Content-Type: application/json" \
      -d '{"model":"zeus-1.0-image-to-video","image":"https://example.com/your-image.jpg","prompt":"Subtle natural motion, cinematic lighting","resolution":"480p","duration":5}'

### Zeus 1.0 — Image to Video 480p

- Model id: `zeus-1.0-image-to-video-480p`
- Family: Zeus 1.0
- Endpoint: POST /v1/video/generations
- Output: video
- Pricing: $0.40 (480p, 5s) / run
- Budget image-to-video at 480p, 5s clips. Supports a negative prompt and automatic prompt expansion.

Parameters:
- `model` · string · REQUIRED — The model id. Options: "zeus-1.0-image-to-video-480p".
- `image` · string (URL) · REQUIRED — Public URL of the reference image to animate. JPEG/PNG/WEBP/BMP, max 10MB.
- `prompt` · string · REQUIRED — What to generate. Max 2500 characters.
- `duration` · integer · optional — Clip length in seconds. Options: 5. Default: 5.
- `negative_prompt` · string · optional — Things to avoid in the output.
- `enable_prompt_expansion` · boolean · optional — Auto-expand a short prompt into a richer script. Default: false.
- `seed` · integer · optional — Reproducible results. -1 (or omit) for random. Default: -1.

Example request body:

    {
      "model": "zeus-1.0-image-to-video-480p",
      "image": "https://example.com/your-image.jpg",
      "prompt": "Subtle natural motion, cinematic lighting",
      "duration": 5
    }

curl:

    curl -X POST https://api18.dev/v1/video/generations \
      -H "Authorization: Bearer $API18_KEY" \
      -H "Content-Type: application/json" \
      -d '{"model":"zeus-1.0-image-to-video-480p","image":"https://example.com/your-image.jpg","prompt":"Subtle natural motion, cinematic lighting","duration":5}'

## 7. Recommended: synchronous, no polling

JavaScript:

    const res = await fetch('https://api18.dev/v1/generate?wait=true', {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.API18_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({"model":"centaurus-1.0-text-to-video","prompt":"A cinematic shot of a city street at night, neon reflections on wet pavement, slow dolly-in","resolution":"720p","aspect_ratio":"16:9","duration":5}),
    });
    const job = await res.json();
    console.log(job.data[0].url); // finished output

Python:

    import os, requests
    job = requests.post('https://api18.dev/v1/generate?wait=true',
        headers={'Authorization': f"Bearer {os.environ['API18_KEY']}"},
        json={'model': "centaurus-1.0-text-to-video", 'prompt': "A cinematic shot of a city street at night, neon reflections on wet pavement, slow dolly-in", 'resolution': "720p", 'aspect_ratio': "16:9", 'duration': 5}).json()
    print(job['data'][0]['url'])

## 8. Alternative: async + polling

Omit `?wait=true`, then poll until done (use this for very long jobs):

    let job = await fetch('https://api18.dev/v1/generate', {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.API18_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({"model":"centaurus-1.0-text-to-video","prompt":"A cinematic shot of a city street at night, neon reflections on wet pavement, slow dolly-in","resolution":"720p","aspect_ratio":"16:9","duration":5}),
    }).then(r => r.json());
    while (job.status !== 'completed' && job.status !== 'failed') {
      await new Promise(r => setTimeout(r, 3000));
      job = await fetch('https://api18.dev/v1/jobs/' + job.id, {
        headers: { Authorization: `Bearer ${process.env.API18_KEY}` },
      }).then(r => r.json());
    }
    if (job.status === 'failed') throw new Error(job.error || 'generation failed');
    console.log(job.data.map(d => d.url));

## 9. Errors

Errors return a non-2xx status and a JSON body: `{ "error": { "type": string, "message": string, "details"?: any } }`. Common types:
- 401 `missing_authorization` / `invalid_api_key` — bad or missing Bearer key.
- 400 `invalid_request` — body failed validation; see `details` for which field.
- 402 `insufficient_balance` — add credits in the dashboard Billing page.
- 402 `paid_balance_required` — your balance is welcome (promo) credit only, which the API can't use. Add paid credit in Billing. (Promo credit works in the dashboard playground.)
- 404 `model_not_found` — unknown `model` id.
- 404 `job_not_found` — the job id doesn't exist or has expired.
- 502 `generation_unavailable` — transient; retry.

## 10. Notes

- `image` / `images` must be PUBLIC URLs the server can fetch (not local file paths or data URIs).
- Always send `Content-Type: application/json`.
- Welcome (promo) credit only works in the dashboard playground; the API requires paid balance.
- Output files expire (see `retention_days`); download and store them yourself if you need them long-term.