One API
All Models

Faster access More reliable Lower cost

API BASE URL

/v1

View Docs

QUICK START

Start in Three Steps

Sign In

Open your user center to view only your own balance, access, and usage.

Issue a Key

Name the key, set its limits, and use every enabled model.

Switch the URL

Set the API Base URL in your client and keep its native protocol.

Getting started

Quickstart

From sign-up to your first request in about five minutes.

Create an account

Top up

Open the console wallet and pay with PayPal — Visa, Mastercard and Amex work directly without a PayPal account. Minimum $1.

Create an API key

Create a key on the console API Keys page, copy it and store it safely.

Send your first request

Replace YOUR_API_KEY in the command below with your key.

Your first request

curl

curl https://api.luckyapi.online/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Introduce yourself in one sentence"
  }'

Tip

A JSON response means the whole chain works. Model names follow the live list on the pricing page.

Next steps

Auth & endpoints — the base URL and request headers
CC Switch — the easiest way to connect a coding tool
GPT Image — call the media APIs directly

Getting started

Auth & endpoints

Every request goes to the same base URL, authenticated with your API key as a Bearer token.

API base URL

https://api.luckyapi.online

Request header

Authorization: Bearer YOUR_API_KEY

Endpoint overview

Protocol / capability	Endpoint
OpenAI Responses protocol	POST `/v1/responses`
OpenAI Chat Completions	POST `/v1/chat/completions`
Anthropic Messages protocol	POST `/v1/messages`
Model list	GET `/v1/models`
Image generation & edits	POST `/v1/images/generations · /v1/images/edits`
Video generation (async)	POST `/v1/videos/generations`

Request bodies match each official protocol; complete runnable examples for the media APIs live in the chapters on the left.

Next steps

CC Switch — the easiest way to connect a coding tool
Codex CLI / Desktop — the shared user-level config

Coding tools

CC Switch

Manage providers through a GUI — the simplest way to connect Codex and Claude Code.

Setup steps

1Open CC Switch and add a custom provider.
2Choose Codex or Claude and enter the matching base URL below.
3Enter your LuckyAPI key, then enable the provider.
4If the target app is already running, restart it.

Configuration

Codex

https://api.luckyapi.online/v1

Claude Code

https://api.luckyapi.online

API Key

YOUR_API_KEY

Open the CC Switch provider guide

Next steps

Codex CLI / Desktop — connect by writing the config file yourself
Claude Code — native endpoint configuration

Coding tools

Codex CLI / Desktop

Codex CLI and Codex Desktop share the same user-level config when they run under the same system user and CODEX_HOME. After saving, restart Codex Desktop or open a new Codex CLI session.

Shared config

Config file~/.codex/config.toml

~/.codex/config.toml

model = "gpt-5.6-sol"
model_provider = "luckyapi"

[model_providers.luckyapi]
name = "LuckyAPI"
base_url = "https://api.luckyapi.online/v1"
wire_api = "responses"
requires_openai_auth = false
experimental_bearer_token = "YOUR_API_KEY"

Next steps

Claude Code — configure the other coding tool
GPT Image — call the media APIs directly

Coding tools

Claude Code

Set the native endpoint and auth token in the Claude Code user settings — configure once, use continuously.

Config file ~/.claude/settings.json

~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.luckyapi.online",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY"
  }
}

Tip

Restart the client after saving the config.

Next steps

Codex CLI / Desktop — the shared user-level config
FAQ — troubleshoot connection issues

Media APIs·OpenAI Images

GPT Image

Supports both text-to-image and reference-image edits. Image requests are usually slower than text — give your client a longer timeout.

POST/v1/images/generations

POST/v1/images/edits

Text to image (JSON)

bash

curl -sS --max-time 600 \
  https://api.luckyapi.online/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A red apple on a wooden table, square 1:1 composition",
    "n": 1,
    "response_format": "b64_json"
  }' \
  -o image-response.json

Reference-image edit (multipart, 1–16 images)

bash

curl -sS --max-time 600 \
  https://api.luckyapi.online/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Combine the references into one cyberpunk scene, keep the subjects and use a square 1:1 composition" \
  -F "image[]=@./reference-1.png" \
  -F "image[]=@./reference-2.png" \
  -F "image[]=@./reference-3.png" \
  -F "n=1" \
  -F "response_format=b64_json" \
  -o image-edit-response.json

Note

When uploading 1–16 reference images, repeat one image[] field per file inside the same multipart request; do not join multiple paths into a single field.
The current gpt-image-2 route needs the desired aspect ratio spelled out in the prompt, e.g. 1:1, 16:9 or 9:16. The size and quality compatibility fields are still forwarded, but the upstream may normalize them to auto, so exact pixel sizes or quality tiers are not guaranteed.
n must be a positive integer and requests multiple results; the final count is decided upstream. Every returned image appears in data[].b64_json and is billed individually, so a larger n also increases time, response size and cost.

Next steps

Grok Image — xAI text-to-image and reference edits
Grok Video 1.5 — async video generation

Media APIs·xAI Imagine

Grok Image

Use the same LuckyAPI key for Grok text-to-image, or edit up to 3 local reference images.

POST/v1/images/generations

POST/v1/images/edits

Text to image (JSON)

bash

curl -sS --fail-with-body --max-time 600 \
  https://api.luckyapi.online/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-quality",
    "prompt": "A cinematic spacecraft leaving a Martian canyon",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1,
    "response_format": "url"
  }' \
  -o grok-image-response.json

Inspect the response and download the first image

bash

RESPONSE=grok-image-response.json

jq . "$RESPONSE"
URL=$(jq -er '.data[0].url' "$RESPONSE") || exit 1
curl -fL "$URL" -o grok-image.png

Reference-image edit (multipart, 1–3 images)

bash

curl -sS --fail-with-body --max-time 600 \
  https://api.luckyapi.online/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=grok-imagine-image-quality" \
  -F "prompt=Combine the subjects into one cinematic cyberpunk scene" \
  -F "image=@./reference-1.png" \
  -F "image=@./reference-2.png" \
  -F "image=@./reference-3.png" \
  -o grok-image-edit-response.json

Note

When uploading 1–3 local files, repeat the image field inside the same multipart request. LuckyAPI converts the files into the JSON image objects xAI expects; when aspect_ratio is not set, the output follows the first input image.
Use aspect_ratio to control the frame; resolution only accepts 1k or 2k. n requests multiple results, and every returned image is billed individually.
The default response returns temporary data[].url links — download them promptly. When downloading an edit result, change RESPONSE in the download step to grok-image-edit-response.json; set response_format to b64_json if you need the image data inline.

Next steps

Grok Video 1.5 — async video generation
Gemini Omni — Google video generation

Media APIs·xAI Imagine

Grok Video 1.5

Video generation is asynchronous: submit a job, poll its status when needed, then let the protected content endpoint wait and download the MP4 for you.

POST/v1/videos/generations

GET /v1/videos/{id} and GET /v1/videos/{id}/content

Step 1: submit a text-to-video job

bash

API_KEY="YOUR_API_KEY"
BASE="https://api.luckyapi.online"

ID=$(curl -fsS "$BASE/v1/videos/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "A cinematic spacecraft leaving a Martian canyon",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }' \
  | jq -er '.request_id') || exit 1

printf 'Request ID: %s\n' "$ID"

Step 2: poll the job status

bash

curl -fsS "$BASE/v1/videos/$ID" \
  -H "Authorization: Bearer $API_KEY" | jq .

Step 3: wait automatically and download the MP4

bash

curl -fSL --retry 120 --retry-delay 5 --retry-all-errors \
  "$BASE/v1/videos/$ID/content" \
  -H "Authorization: Bearer $API_KEY" \
  -o grok-video.mp4

Tip

pending means still generating; done means the video is ready; failed or expired means the job did not finish — check the upstream error in the full status response. The download command retries every 5 seconds for up to about 10 minutes and never saves an HTTP error body as an MP4.

Image to video (1 local first-frame image)

bash

base64 < ./reference.png | tr -d '\n' | \
jq -Rs '{
  model: "grok-imagine-video-1.5",
  prompt: "Animate this still image with a slow cinematic camera move",
  image: {url: ("data:image/png;base64," + .)},
  duration: 10,
  resolution: "720p"
}' > grok-video-request.json

curl -sS --fail-with-body \
  https://api.luckyapi.online/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @grok-video-request.json | jq .

image accepts one public HTTPS URL, base64 data URI or file_id, and uses it as the first frame. Once you have the request_id, reuse the status and content endpoints above.

Multi-reference video (JSON, 1–7 images)

bash

curl -sS --fail-with-body \
  https://api.luckyapi.online/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "Use the person from <IMAGE_0> and the clothing from <IMAGE_1>",
    "reference_images": [
      {"url": "https://example.com/person.png"},
      {"url": "https://example.com/clothing.png"}
    ],
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }' | jq .

Note

reference_images accepts 1–7 public URLs, base64 data URIs or file_ids; they guide the video content without locking the first frame. Multi-reference mode supports up to 720p.
image and reference_images cannot be combined. Durations of 1–15 seconds are supported; aspect ratios 1:1, 16:9, 9:16, 4:3, 3:4, 3:2 and 2:3; text-to-video and image-to-video support 480p, 720p and 1080p.

Next steps

Gemini Omni — Google video generation
FAQ — troubleshoot request issues

Media APIs·Google Flow

Gemini Omni

Gemini Omni is an async video API supporting text-to-video, one local first-frame image, or 1–5 local reference images; each request returns one MP4.

POST/v1/videos/generations

Step 1: submit a text-to-video job

bash

API_KEY="YOUR_API_KEY"
BASE="https://api.luckyapi.online"

ID=$(curl -fsS "$BASE/v1/videos/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash",
    "prompt": "A cinematic sunrise over the ocean with a slow camera push",
    "duration": 8,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }' \
  | jq -er '.request_id') || exit 1

printf 'Request ID: %s\n' "$ID"

Step 2: poll the job status

bash

curl -fsS "$BASE/v1/videos/$ID" \
  -H "Authorization: Bearer $API_KEY" | jq .

Step 3: wait automatically and download the MP4

bash

curl -fSL --retry 120 --retry-delay 5 --retry-all-errors \
  "$BASE/v1/videos/$ID/content" \
  -H "Authorization: Bearer $API_KEY" \
  -o gemini-omni.mp4

Tip

pending means still generating; done means the MP4 is ready; failed means this generation did not finish — check the upstream error in the full status response. The download command retries every 5 seconds for up to about 10 minutes.

Image to video (1 local first-frame image)

bash

curl -sS --fail-with-body \
  https://api.luckyapi.online/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gemini-omni-flash" \
  -F "prompt=Animate this first frame with a slow cinematic camera move" \
  -F "duration=8" \
  -F "aspect_ratio=16:9" \
  -F "resolution=720p" \
  -F "image=@./first-frame.jpg;type=image/jpeg" | jq .

image accepts exactly one local PNG or JPEG and locks it as the first frame. Once you have the request_id, reuse the status and content endpoints above.

Multi-reference video (multipart, 1–5 images)

bash

curl -sS --fail-with-body \
  https://api.luckyapi.online/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gemini-omni-flash" \
  -F "prompt=Use the person and wardrobe from the reference images" \
  -F "duration=8" \
  -F "aspect_ratio=9:16" \
  -F "resolution=720p" \
  -F "reference_images=@./person.png;type=image/png" \
  -F "reference_images=@./wardrobe.jpg;type=image/jpeg" | jq .

Note

When uploading 1–5 local PNG or JPEG images, repeat the reference_images field inside the same multipart request; each image must stay under 5 MiB and 25 megapixels.
duration, aspect_ratio and resolution are required. Only durations of 4, 6, 8 or 10 seconds are supported; only 16:9 and 9:16 aspect ratios; only 720p and 1080p resolutions. Each request generates exactly one video, so n can only be 1; image and reference_images cannot be combined.
720p and 1080p are billed at the same per-request price shown on the pricing page. 1080p runs a second render pass after the base generation, so it takes longer; if that re-render fails the job fails — it never silently falls back to 720p.

Next steps

FAQ — troubleshoot request issues
Quickstart — review the onboarding flow

Help

FAQ

Requests return 401 Unauthorized

Check the Authorization: Bearer header and make sure the key was copied in full; you can recreate keys on the API Keys page at any time.

Model not found or no permission

Model names follow the live list on the pricing page — you can also query GET /v1/models with your key; also confirm that your key's group has access to the model.

Top-up has not arrived

Crediting is driven by verified PayPal payment notifications and usually completes within seconds; if an order stays pending, check its status on the wallet page — pending orders can be cancelled and retried.

Image or video requests time out

Generation requests are slower than text — raise your client timeout to 600 seconds; the video API is asynchronous, so submit first and poll the status as shown in the video chapters.

Next steps

Quickstart — review the onboarding flow
Auth & endpoints — verify the base URL and headers

gpt-5.6-lunaOpenAI

$0.02 / $0.12~~$0.2 / $1.2~~-90%

gpt-5.6-terraOpenAI

$0.2 / $1.2~~$2 / $12~~-90%

gpt-5.6-solOpenAI

$0.5 / $3~~$5 / $30~~-90%

gpt-image-2OpenAI

$0.06–$0.10

grok-imagine-imagexAI

$0.04

grok-imagine-image-qualityxAI

$0.06

grok-imagine-video-1.5xAI

$0.007–$0.01

gemini-omni-flashGoogle

$0.08


gpt-5.3-codex-spark	OpenAI	$0.175	$0.0175		$1.4	-90%
gpt-5.4	OpenAI	$0.25	$0.025		$1.5	-90%
gpt-5.4-mini	OpenAI	$0.075	$0.0075		$0.45	-90%
gpt-5.5	OpenAI	$0.5	$0.05		$3	-90%
gpt-5.6-luna	OpenAI	$0.02	$0.002	$0.025	$0.12	-90%
gpt-5.6-sol	OpenAI	$0.5	$0.05	$0.625	$3	-90%
gpt-5.6-terra	OpenAI	$0.2	$0.02	$0.25	$1.2	-90%

One APIAll Models

Start in Three Steps

Sign In

Issue a Key

Switch the URL

Your first request

Next steps

API base URL

Request header

Endpoint overview

Next steps

Setup steps

Configuration

Next steps

Shared config

Config file~/.codex/config.toml

Next steps

Config file ~/.claude/settings.json

Next steps

Text to image (JSON)

Reference-image edit (multipart, 1–16 images)

Next steps

Text to image (JSON)

Inspect the response and download the first image

Reference-image edit (multipart, 1–3 images)

Next steps

Step 1: submit a text-to-video job

Step 2: poll the job status

Step 3: wait automatically and download the MP4

Image to video (1 local first-frame image)

Multi-reference video (JSON, 1–7 images)

Next steps

Step 1: submit a text-to-video job

Step 2: poll the job status

Step 3: wait automatically and download the MP4

Image to video (1 local first-frame image)

Multi-reference video (multipart, 1–5 images)

Next steps

Next steps

Project Sponsorship

Channel Revenue Share

Information we process

Account identity

How information is used

Sharing and retention

Your choices

Accounts and credentials

Acceptable use

Usage and billing

Availability

Changes

API Key

Top Up

Top-up Orders

Usage Trends & Cost Distribution

Token & Request Trend

Cost Distribution

Daily Usage

Request Details

One API
All Models