HL Gaming Official Free Fire Outfits, Banners, Avatars & More API Documentation

Free Fire Outfits, Banners, Avatars & More API Documentation

The Free Fire Outfits, Banners, Avatars & More API allows you to convert any valid in-game item code into its original, high-resolution JPEG image—completely watermark-free.

Images served in standard JPEG format (great browser support, small file size).
Each URL is cryptographically signed (JWT) and valid for exactly 5 minutes.
Per-user quotas, detailed analytics, and enterprise-grade security by default.

🚫 API usage is currently limited to 25 requests per day on the free plan. This includes all actions such as ban status checks, rank lookups, and related endpoints. To raise the limit and unlock features like advanced rank data, ban history details, and real-time moderation, consider upgrading your plan.

🚨 Security Warning: Never expose your useruid or api key directly in client-side code (such as HTML, JavaScript, or public repositories). These credentials are sensitive and must be securely stored and handled on your server. If exposed, anyone could misuse your account, exhaust your API limits, or access protected data on your behalf.

🎉 Beta Update Available!

Unified Avatar + Banner API request now supported
Better image caching and rendering performance
Atomic response guarantees for frontend safety
Short-lived pre-signed URLs to secure media access

Authentication

Every request must include:

useruid (string): Your HL GAMING UID.
api (string): Your secret API key.

Pass them as HTTPS query parameters. Never expose these in client-side code.

GET /api?sectionName=image&useruid=YOUR_UID&api=YOUR_KEY&img_code=ITEM_CODE

Authentication Errors

401 Unauthorized – missing or malformed credentials.
403 Forbidden – provided useruid or api is invalid.

Rate Limits & Plans

We offer tiered plans to suit your needs:

Plan	Requests / 24h	Features	Price (USD/mo)
Free	25	Basic support, standard images	$0
Pro	1,000	Faster JWT signing, custom caching headers	$19
Enterprise	Unlimited	Dedicated SLAs, burst throughput, audit logs	Contact sales

Exceeding your quota returns 429 Too Many Requests. Quotas reset atomically when your personal limitReset timestamp passes.

Endpoint URL

Base URL: https://hl-gaming-official-api-ff-img.vercel.app/api Only GET requests accepted. All inputs via query string.

Parameters

The following query parameters must be supplied on every request to the API. All parameters are case-sensitive.

Parameter	Required	Type	Description	Example
`sectionName`	Yes	string	Must be exactly `image` to invoke the image-proxy endpoint.	`image`
`useruid`	Yes	string	Your HL GAMING user UID. Used for authentication and per-user logging.	`abc123UID`
`api`	Yes	string	Your secret API key. Keep this value confidential.	`hlgamingKey`
`img_code`	Yes	string	The in-game item code to look up. Numeric or alphanumeric. Case-sensitive.	`203000304`

Notes:

Always URL-encode img_code if it contains special characters (e.g. spaces, symbols).
Any additional or unsupported parameters will be ignored by the endpoint.
Passing cacheBuster helps avoid client-side or CDN caching if you need a guaranteed fresh URL.

JWT Structure

The signed URL embeds a JWT with:

code: the img_code you provided.
iat: issued-at UNIX timestamp.
exp: expiry UNIX timestamp (5 minutes later).

Example decoded header & payload:

Header: { "alg": "HS256", "typ": "JWT" } Payload: { "code": "203000304", "iat": 1747127656, "exp": 1747127956 }

Response Schema

200 OK returns JSON:

{ "source": "HL Gaming Official – Image Proxy", "endpoint": "image", "result": { "url": "{signed_jpeg_url}" }, "usage": { "usedToday": 12, "dailyLimit": 25, "remainingToday": 13 } }

result.url: Direct JPEG link, expires in 5 minutes.
usage: Tracks your daily consumption.

Example Request

curl -X GET "https://hl-gaming-official-api-ff-img.vercel.app/api?sectionName=image&useruid=abc123UID&api=hlgamingKey&img_code=203000304&cacheBuster=1616161616"

Adding cacheBuster forces fresh signing even if the same img_code was requested moments ago.

Example Response

{ "source": "HL Gaming Official – Image Proxy", "endpoint": "image", "result": { "url": "https://ff-outfits-hl-gaming-official-api.vercel.app/api/image/resource/ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9. eyJjb2RlIjoiMjAzMDAwMzA0IiwiaWF0IjoxNzQ3MTI3NjU2LCJleHAiOjE3NDcxMjc5NTZ9. vPlnUWEt7cFfFiaTYttBYz_WSwZhha96dknobvoY1bo.jpg" }, "usage": { "usedToday": 13, "dailyLimit": 25, "remainingToday": 12 } }

After 5 minutes:

{"code":"AUTH_ERR","message":"Link invalid or expired."}

Error Responses

400 Bad Request

This status is returned when required query parameters are missing, malformed, or invalid.

{
  "error": "Missing required parameters"
}

Check if all mandatory query parameters (e.g., sectionName, useruid, api, img_code) are correctly supplied.
Make sure no parameter is empty or null.
Case sensitivity matters — ensure values are correctly cased.

401 Unauthorized / 403 Forbidden

These errors relate to failed authentication or invalid API credentials.

{
  "error": "Auth Failed! Please Check Your User ID & Try Again.."
}
{
  "error": "Invalid API key."
}

401: The useruid is missing, malformed, or not recognized.
403: The api key is incorrect or unauthorized.
Ensure both credentials are valid and match an active registered user.

429 Too Many Requests

Triggered when a user exceeds their daily usage quota based on their plan.

{
  "error": "Quota exceeded. Upgrade your plan."
}

The Free Plan allows only 25 requests per 24 hours.
The Pro Plan allows 1000 requests per day.
Quotas reset every 24 hours from your local timezone registration time.
Monitor the usage.remainingToday field in successful responses to avoid hitting this error.

502 Bad Gateway

Occurs when the proxy server fails to retrieve or parse content from an upstream system.

{
  "error": "External API error",
  "details": "Connection timed out or service unavailable"
}

This is typically a transient issue on the server or external network.
No user-side action is needed — retry after a brief delay.
Report to support if this persists over multiple hours.

AUTH_ERR (Expired Signed URL)

Returned when attempting to use a previously valid URL that has now expired.

{
  "code": "AUTH_ERR",
  "message": "Link invalid or expired."
}

Signed URLs are valid for exactly 5 minutes from generation time.
Re-request a fresh img_code to receive a new valid link.
To prevent user-side errors, always check if the current timestamp is still within 5 minutes of generation before using the URL.

Beta Mode: Unified Avatar & Banner Fetch

NEW

Last updated: May 24, 2025 – 14:47 UTC by Azhar H, Backend Developer at HL Gaming

Beta Mode enables developers to fetch both a player's avatar outfit image and profile banner in a single unified API request. This optimizes performance and provides atomic response guarantees, making it ideal for modern UIs and real-time use cases such as profile renderers, leaderboard cards, and social overlays.

Internally, the system utilizes a multi-stage rendering pipeline and returns pre-signed image URLs with short-lived validity. This ensures image access is secure, fast, and cacheable without requiring media to be stored locally.

Recommended Use Cases:

Rendering complete Free Fire player profiles in your app or website.
Reducing server round-trips by combining multiple assets into one API call.
Need for temporary but secure access to outfit and banner graphics for visual UI.

Endpoint

GET or POST https://hl-gaming-official-api-ff-img.vercel.app/api

Both GET and POST are supported for flexibility. Use GET for simple browser testing, and POST for clean server integrations.

Parameters (Advanced)

Parameter	Type	Required	Description
`sectionName`	string	Yes	Must be `image` to use the image rendering service.
`useruid`	string	Yes	Your developer account ID issued during registration with HL Gaming.
`api`	string	Yes	Your secure developer access token. Keep it private; do not expose in frontend.
`playeruid`	string	Yes (Beta only)	Free Fire player UID whose outfit and banner you wish to render.
`isBeta`	string	Yes	Set to `true` (as a string) to activate unified mode.
`region`	string	Yes	Player’s region code (e.g. `ind`, `br`, `pk`, `sg`).

Request Examples

GET Example:


      /api?sectionName=image

      &useruid=YOUR_UID

      &api=YOUR_KEY

      &playeruid=9351564274

      &region=pk

      &isBeta=true

POST Example:

{
  "sectionName": "image",
  "useruid": "YOUR_UID",
  "api": "YOUR_KEY",
  "playeruid": "9351564274",
  "region": "pk",
  "isBeta": "true"
}

Response Structure

{
  "source": "HL Gaming – Public API",
  "endpoint": "image",
  "isBeta": true,
  "result": {
    "uid": "9351564274",
    "region": "pk",
    "outfitUrl": "https://api.hlcdn.com/images/outfit-9351564274.png?...",
    "bannerUrl": "https://api.hlcdn.com/images/banner-9351564274.png?..."
  },
  "usage": {
    "usedToday": 42,
    "dailyLimit": 100,
    "remainingToday": 58
  }
}

Each image URL is time-sensitive and expires in approximately 5 minutes. These URLs are cryptographically signed and secured from unauthorized reuse.

Live Preview

👕 Outfit Image

🎌 Banner Images

Error Handling

400 – Bad Request

{ "error": "Missing required parameters." }

Ensure playeruid, region, and isBeta=true are present.

403 – Unauthorized

{ "error": "Invalid developer credentials." }

Check your useruid and api.

429 – Quota Exceeded

{ "error": "Rate limit exceeded. Try again later." }

Quotas are reset daily at midnight UTC.

502 – Image Service Down

{ "error": "Service temporarily unavailable." }

Retry with exponential backoff.

Best Practices

Keep API keys secret: Never expose your developer credentials in client-side code.
Implement retries: Handle 502 errors gracefully by retrying up to 3 times with delay.
Respect cache windows: Use the outfit and banner URLs within their 5-minute TTLs.
Track usage: Display remaining quota to users or throttle calls client-side when near limit.
Secure backend: Route all API calls through a secure server to avoid key leakage.

Developer Tips

Beta Mode is the preferred option for production use cases involving multiple visual assets.
All image URLs are CDN-delivered and optimized for delivery speed. No extra compression is needed.
You can integrate this into React, Vue, Flutter, or Unity frontends using simple fetch() wrappers.
Consider setting up background refresh jobs if you cache player profiles locally.

Best Practices

Cache URLs: Store result.url for up to 5 minutes to reduce API traffic.
Use Cache Buster: Add cacheBuster to force a new signature if needed.
Rotate API Keys: Cycle your api periodically for security.
Monitor Usage: Alert when remainingToday drops below 10% of your quota.
Centralized Logging: Log request/response JSON and timestamps in your system.
SSL Everywhere: Ensure all calls are over HTTPS.

Logging & Analytics

Every request is recorded in hl gaming official database with:

method, endpoint, query
timestamp, status, usedToday
timezone (America/Los_Angeles) for consistency.

Use these logs to:

Audit usage patterns.
Debug failed or slow requests.
Trigger alerts on anomalies (e.g. spike in 502 errors).

FAQ

Q: Why do I get the same URL if I request the same img_code within 5 minutes?
A: JWT payload is identical, so the signed URL remains the same until expiration.

Q: Can I request multiple codes at once?
A: No. Each request handles one code. Parallelize calls or batch on your backend.

Q: How do I upgrade my plan?
A: Visit your dashboard’s “API Access” section and select an upgrade option.

Changelog

v2.2.0 – Added cacheBuster param, improved JWT validation.
v2.1.0 – Exposed usage.remainingToday, enhanced error hierarchy.
v2.0.0 – Migrated to JWT-signed URLs, enforced 5-minute expiry window.
v1.0.0 – Initial launch: image lookup by img_code.

Support

Need help?

Email: support@hlgamingofficial.com
Dashboard ticketing system

HL Gaming API Tester

 Waiting for request...

🚫 API Usage Limit: Free plans are limited to 25 API requests per day. This includes all operations such as checking ban status, rank verification, and other related endpoints. To increase your request limit and unlock additional features such as advanced rank metadata, detailed ban history, and real-time moderation integration, please consider upgrading your plan.

HL Gaming Official Free Fire Outfits, Banners, Avatars & More API Documentation

HL Gaming API Tester

Free Fire ID Check – Check Free Fire Account Info via UID (Rank, Level, Stats,Outfits,Price & More)

HL GAMING OFFICIAL

Contact form

HL GAMING OFFICIAL FAST VIEW

HL Gaming Official Free Fire Outfits, Banners, Avatars & More API Documentation

HL Gaming API Tester

Contact form

HL GAMING OFFICIAL FAST VIEW

Edit Bookmark