Sign In
Open your user center to view only your own balance, access, and usage.
✦ QUICK START
Start in Three Steps
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.
LuckyAPI / Docs
Quick start
From sign-up to your first request in about five minutes.
- 1
Create an account: register with email or Google, then open the console.
- 2
Top up: open Wallet in the console and pay with PayPal — Visa, Mastercard and Amex work without a PayPal account, starting from $1.
- 3
Create an API key: open API Keys in the console, create a key and copy it somewhere safe.
- 4
Send your first request with the command below, replacing YOUR_API_KEY with your key.
First request
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"
}'A JSON response means the chain works end to end. Model names follow the live catalog on the console model page.
Next: connect a coding tool, or call the media APIs directly. CC SwitchGPT Image
Authentication & endpoints
Every request goes to the same Base URL and authenticates with your API key as a Bearer token.
API Base URL
https://api.luckyapi.onlineRequest header
Authorization: Bearer YOUR_API_KEYEndpoints
| OpenAI Responses | POST /v1/responses |
| OpenAI Chat Completions | POST /v1/chat/completions |
| Anthropic Messages | 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 follow each protocol's official format. Full working examples for the media APIs are in their chapters on the left.
Recommended
CC Switch
A graphical provider switcher is the simplest option for Codex and Claude Code.
- 1
Open CC Switch and add a custom provider.
- 2
Choose Codex or Claude, then enter the matching Base URL below.
- 3
Enter your LuckyAPI key and activate the provider.
- 4
Restart the target app if it was already running.
- Codex
https://api.luckyapi.online/v1- Claude Code
https://api.luckyapi.online- API Key
YOUR_API_KEY
Shared configuration
Codex CLI / Desktop
Codex CLI and Codex Desktop use the same user-level configuration when they run as the same system user with the same CODEX_HOME.
Save the file, then restart Codex Desktop or start a new Codex CLI session.
Configuration file
~/.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"Claude Code
Set the native Claude Code endpoint and authentication token once in its user settings.
Configuration file
~/.claude/settings.json
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.luckyapi.online",
"ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY"
}
}Restart the client after saving the configuration.
OpenAI Images
GPT Image
POST /v1/images/*Text-to-image and reference-image editing are both available. Image requests can take longer than text requests, so allow a longer client timeout.
Text to image (JSON)
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.jsonReference image edit (multipart, 1–16 images)
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.jsonUpload 1–16 reference images by repeating the image[] field once per file. Keep every file in the same multipart request; do not combine paths into one field.
For the current gpt-image-2 route, put the desired aspect ratio (for example 1:1, 16:9, or 9:16) in the prompt. The size and quality compatibility fields are forwarded but the upstream may normalize them to auto, so exact pixel dimensions and quality levels are not guaranteed.
n is a positive integer and requests multiple outputs; the upstream decides the final count. Every returned image appears in data[].b64_json and is billed separately, so larger n also increases latency, response size, and cost.
xAI Imagine
Grok Image
POST /v1/images/*Generate images from text or edit up to three local reference images through the same LuckyAPI key.
Text to image (JSON)
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.jsonInspect the response and download the first image
RESPONSE=grok-image-response.json
jq . "$RESPONSE"
URL=$(jq -er '.data[0].url' "$RESPONSE") || exit 1
curl -fL "$URL" -o grok-image.pngReference image edit (multipart, 1–3 images)
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.jsonUpload 1–3 local files by repeating the image field in one multipart request. LuckyAPI converts those files to the JSON image objects expected by xAI; the output follows the first image's aspect ratio unless aspect_ratio is set.
Use aspect_ratio for composition and resolution 1k or 2k for output resolution. n requests multiple outputs and every returned image is billed separately.
The default response uses temporary data[].url values, so download them promptly. To download an edit, set RESPONSE=grok-image-edit-response.json in the download step. Set response_format to b64_json when the client needs embedded image data.
xAI Imagine
Grok Video 1.5
POST /v1/videos/generationsVideo generation is asynchronous: submit a task first, inspect its status when needed, then use the protected content endpoint to wait for and download the MP4.
Step 1: Submit a text-to-video task
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: Check task status
curl -fsS "$BASE/v1/videos/$ID" \
-H "Authorization: Bearer $API_KEY" | jq .Step 3: Wait automatically and download the MP4
curl -fSL --retry 120 --retry-delay 5 --retry-all-errors \
"$BASE/v1/videos/$ID/content" \
-H "Authorization: Bearer $API_KEY" \
-o grok-video.mp4pending means the task is still running. done means the MP4 is ready. failed or expired means generation did not complete; inspect the full status response for the upstream error. The download command retries every 5 seconds for about 10 minutes and does not save HTTP error bodies as MP4 files.
Image to video (one local first-frame image)
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 becomes the first frame. Reuse the returned request_id with the status and content endpoints shown above.
Reference-guided video (JSON, 1–7 images)
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 .reference_images accepts 1–7 public URLs, base64 data URIs, or file_id values as guidance without fixing the first frame. Reference-to-video is limited to 720p.
Do not combine image and reference_images. Duration is 1–15 seconds. Supported aspect ratios are 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.
Google Flow
Gemini Omni
POST /v1/videos/generationsGemini Omni is an asynchronous video API. It supports text-to-video, one local first-frame image, or 1–5 local reference images, and returns one MP4 per request.
Step 1: Submit a text-to-video task
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: Check task status
curl -fsS "$BASE/v1/videos/$ID" \
-H "Authorization: Bearer $API_KEY" | jq .Step 3: Wait automatically and download the MP4
curl -fSL --retry 120 --retry-delay 5 --retry-all-errors \
"$BASE/v1/videos/$ID/content" \
-H "Authorization: Bearer $API_KEY" \
-o gemini-omni.mp4pending means the task is still running. done means the MP4 is ready. failed means generation did not complete; inspect the full status response for the upstream error. The download command retries every 5 seconds for about 10 minutes.
Image to video (one local first-frame image)
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 .The image field accepts exactly one local PNG or JPEG and fixes the first frame. Reuse the returned request_id with the status and content endpoints shown above.
Reference-guided video (multipart, 1–5 images)
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 .Upload 1–5 local PNG or JPEG files by repeating reference_images in one multipart request. Each image must be no larger than 5 MiB or 25 megapixels.
duration, aspect_ratio, and resolution are required. Duration is 4, 6, 8, or 10 seconds; aspect ratio is 16:9 or 9:16; resolution is 720p or 1080p. A request produces one video, so n can only be 1. Do not combine image with reference_images.
720p and 1080p use the same per-request price shown on the Pricing page. 1080p performs a second upscaling render after base generation, so it takes longer; if that render fails, the task fails rather than silently returning 720p.
FAQ
Requests return 401 Unauthorized
Check the Authorization: Bearer header and make sure the key was copied in full. Keys can be recreated at any time on the API Keys page.
The model is reported as missing or not permitted
Model names follow the live catalog on the console model page; make sure your key's group has access to the model you request.
A top-up has not been credited
Crediting is driven by the verified PayPal payment notification and normally lands within seconds. If an order stays pending for several minutes, check its status on the Wallet page — pending orders can be cancelled and retried.
Image or video requests time out
Generation takes longer than text: raise the client timeout to 600 seconds. Video endpoints are asynchronous — submit the task, then poll its status as shown in the video chapters.
Models & Pricing
Model
Provider
Input
Cache read
Cache write
Output
No matching models.
PARTNERSHIPS
Partner with LuckyAPI
Project Sponsorship
Token sponsorship for quality projects, helping them reach more users.
Channel Revenue Share
A 30% token revenue share for quality software and agents: integrate our tokens into your product and earn on every user's usage.
Reach us through the channel where you received LuckyAPI access.
Privacy Policy
Effective: July 24, 2026
This policy explains how LuckyAPI handles information while providing accounts, API access, usage, and billing features.
Information we process
We process account email and username, session and security metadata, and usage, billing, and payment-status records.
Account identity
Account identity and credentials are processed to authenticate you, protect access, and recover your account.
How information is used
Information is used to create and protect accounts, issue local sessions, provide API service, record usage, settle charges, prevent abuse, and meet necessary security and legal obligations.
Sharing and retention
We do not sell personal information. Information is processed only as needed for hosting, payment, security, or legal compliance, and retained only for operational, security, accounting, and legal needs.
Your choices
To request access, correction, or deletion of account data, use the contact channel through which your LuckyAPI access was provided.
Terms of Service
Effective: July 24, 2026
By using LuckyAPI, you agree to these service terms.
Accounts and credentials
Provide accurate account information and protect sessions, passwords, and API keys. Accounts and keys may not be sold, leased, or used for unauthorized access.
Acceptable use
Do not use the service unlawfully, infringe rights, bypass access controls, attack systems, distribute malware, or interfere with other users or upstream services.
Usage and billing
Billing is based on LuckyAPI records of requests, tokens, models, rates, and applicable multipliers. Top-ups, refunds, and payment status follow verified payment results and the rules shown in the product.
Availability
Upstream models and networks can change or fail. LuckyAPI may limit or suspend access for security, compliance, maintenance, or abuse risk, while making reasonable efforts to keep records accurate and service available.
Changes
Material changes update the effective date on this page. Continued use after a change means acceptance of the updated terms.