Documentation
API quickstart
Everything you need to call FZ-craft from your code: authentication, endpoints, streaming, reasoning, images, limits, errors and billing — with copy-paste examples in curl, Python and Node.js.
Introduction
FZ-craft gives you one OpenAI-compatible REST API for chat, reasoning, vision, tool calling, embeddings and image generation across many models. If you already use an OpenAI SDK, switching takes two lines: set the base URL and use your FZ-craft API key. Request and response bodies, streaming and error shapes all follow the OpenAI format.
Base URL
https://fzcraft.pikonox.com/v1fz_live_…Authorization: Bearer fz_live_…Try it without code
Every model is also available in the Playground and Image Studio once you sign in.Authentication
Create a key in Dashboard → API keys. Keys start with fz_live_ and are shown only once, so store them in a secret manager or an environment variable. Send the key on every request in the Authorization header as a bearer token. An x-api-key header is accepted too.
curl https://fzcraft.pikonox.com/v1/models \
-H "Authorization: Bearer $API_KEY"
# x-api-key works too
curl https://fzcraft.pikonox.com/v1/models \
-H "x-api-key: $API_KEY"Each key can be locked down independently. Limits are checked before the request reaches a model:
Keep keys on the server
Anyone with your key can spend your quota. Don't ship keys in browser or mobile app code — call FZ-craft from your backend, and give each app its own key with tight limits.Base URL
All endpoints live under https://fzcraft.pikonox.com/v1. Use it as the base_url / baseURL in any OpenAI SDK, or in any framework or tool that lets you set an OpenAI-compatible endpoint. The SDK appends paths like /chat/completions for you.
export API_KEY="fz_live_..."
# Optional: the official OpenAI SDKs pick these up automatically
export OPENAI_BASE_URL="https://fzcraft.pikonox.com/v1"
export OPENAI_API_KEY="$API_KEY"# pip install openai
import os
from openai import OpenAI
client = OpenAI(
base_url="https://fzcraft.pikonox.com/v1",
api_key=os.environ["API_KEY"], # fz_live_...
)Every sample below is self-contained and already points at this base URL. Code tabs remember the language you pick.
Chat completions
POST https://fzcraft.pikonox.com/v1/chat/completions generates a reply from a list of messages. It takes the standard OpenAI parameters; anything not listed below is passed through to the model unchanged.
from openai import OpenAI
client = OpenAI(base_url="https://fzcraft.pikonox.com/v1", api_key="fz_live_...")
resp = client.chat.completions.create(
model="deepseek-v4.1-flash",
messages=[
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Write a haiku about latency."},
],
temperature=0.7,
max_tokens=200,
)
print(resp.choices[0].message.content)
print(resp.usage.total_tokens, "tokens"){
"id": "chatcmpl-8f2c…",
"object": "chat.completion",
"created": 1763116800,
"model": "deepseek-v4.1-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Packets cross the sea…"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 27,
"completion_tokens": 19,
"total_tokens": 46
}
}Streaming
With "stream": true the response is a text/event-stream. Each event is a data: line holding a chat.completion.chunk; the stream ends with data: [DONE]. Usage is only sent when you ask for it with stream_options.include_usage — it arrives in a final chunk with an empty choices array.
from openai import OpenAI
client = OpenAI(base_url="https://fzcraft.pikonox.com/v1", api_key="fz_live_...")
stream = client.chat.completions.create(
model="deepseek-v4.1-flash",
messages=[{"role": "user", "content": "Count to five."}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if chunk.usage: # final chunk, only with include_usage
print("\n", chunk.usage)data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"deepseek-v4.1-flash","choices":[{"index":0,"delta":{"role":"assistant","content":"One"}}]}
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"deepseek-v4.1-flash","choices":[{"index":0,"delta":{"content":", two"}}]}
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"deepseek-v4.1-flash","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"deepseek-v4.1-flash","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":9,"total_tokens":21}}
data: [DONE]- Lines starting with
:are keep-alive comments — ignore them (the SDKs do). - If the model fails mid-stream you receive one
data: {"error": {...}}event withcode: "upstream_error"and the stream closes. - Closing the connection cancels generation; you're only billed for tokens produced so far.
Reasoning output
Models with the reasoning capability (for example deepseek-v4.1-flash) think before they answer. The chain of thought is returned separately from the answer in message.reasoning_content, or as delta.reasoning_content chunks that arrive before delta.content when streaming. Show it, log it or ignore it — the final answer is always in content.
from openai import OpenAI
client = OpenAI(base_url="https://fzcraft.pikonox.com/v1", api_key="fz_live_...")
resp = client.chat.completions.create(
model="deepseek-v4.1-flash",
messages=[{"role": "user", "content": "Is 1001 a prime number?"}],
)
msg = resp.choices[0].message
print("thinking:", getattr(msg, "reasoning_content", None))
print("answer:", msg.content)
# Streaming: reasoning arrives in delta.reasoning_content before delta.content
stream = client.chat.completions.create(
model="deepseek-v4.1-flash",
messages=[{"role": "user", "content": "Is 1001 a prime number?"}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta if chunk.choices else None
if delta is not None and getattr(delta, "reasoning_content", None):
print(delta.reasoning_content, end=""){
"model": "deepseek-v4.1-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"reasoning_content": "1001 = 7 × 11 × 13, so it has divisors other than 1 and itself…",
"content": "No. 1001 = 7 × 11 × 13."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 14,
"completion_tokens": 96,
"total_tokens": 110,
"completion_tokens_details": { "reasoning_tokens": 81 }
}
}usage.completion_tokens_details.reasoning_tokens when the model provides it. Use max_tokens to cap them.Vision input
Models with the vision capability accept images inside a user message. Use the OpenAI content-parts format: a text part plus one or more image_url parts pointing at an https:// URL or a base64 data: URL.
import base64
from openai import OpenAI
client = OpenAI(base_url="https://fzcraft.pikonox.com/v1", api_key="fz_live_...")
with open("receipt.png", "rb") as f:
b64 = base64.b64encode(f.read()).decode()
resp = client.chat.completions.create(
model="seed-2.1-turbo",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Extract the total from this receipt."},
{"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
],
}],
)
print(resp.choices[0].message.content)- Sending images to a model without vision returns 400
vision_not_supported. - The JSON body may be up to 25 MB, including base64 images. Larger bodies get 413
request_too_large. - Image inputs count toward input tokens, as reported by the model.
Tool calling
Describe functions in tools. When the model wants one, the reply has finish_reason: "tool_calls" and a tool_calls array. Run the function, append the assistant message and a role: "tool" message with the matching tool_call_id, then call the API again. tool_choice and parallel_tool_calls are passed through. Look for the tools capability in the model list.
import json
from openai import OpenAI
client = OpenAI(base_url="https://fzcraft.pikonox.com/v1", api_key="fz_live_...")
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Current weather for a city",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}]
messages = [{"role": "user", "content": "Do I need an umbrella in Lahore today?"}]
first = client.chat.completions.create(model="qwen3.8-27b", messages=messages, tools=tools)
call = first.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments) # {"city": "Lahore"}
messages.append(first.choices[0].message)
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps({"city": args["city"], "rain_chance": 0.7}),
})
final = client.chat.completions.create(model="qwen3.8-27b", messages=messages, tools=tools)
print(final.choices[0].message.content){
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_7Yx…",
"type": "function",
"function": { "name": "get_weather", "arguments": "{\"city\":\"Lahore\"}" }
}
]
},
"finish_reason": "tool_calls"
}
]
}Embeddings
POST https://fzcraft.pikonox.com/v1/embeddings turns text into vectors for search, clustering and RAG. input can be a string or an array of strings. Embedding requests count input tokens only, and need the embeddings scope.
from openai import OpenAI
client = OpenAI(base_url="https://fzcraft.pikonox.com/v1", api_key="fz_live_...")
resp = client.embeddings.create(
model="fz-embed-v1",
input=["The quick brown fox", "jumps over the lazy dog"],
)
vectors = [d.embedding for d in resp.data]
print(len(vectors), "vectors of", len(vectors[0]), "dimensions"){
"object": "list",
"data": [
{ "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, …] },
{ "object": "embedding", "index": 1, "embedding": [0.0311, 0.0094, …] }
],
"model": "fz-embed-v1",
"usage": { "prompt_tokens": 10, "total_tokens": 10 }
}Image generation & edits
POST https://fzcraft.pikonox.com/v1/images/generations creates images from a prompt; POST https://fzcraft.pikonox.com/v1/images/edits transforms an uploaded image. Both need the images scope and are paid per image from your separate image wallet, not from your token allowance.
Generate
from openai import OpenAI
client = OpenAI(base_url="https://fzcraft.pikonox.com/v1", api_key="fz_live_...")
# OpenAI-style size
img = client.images.generate(
model="sunburst-2.5",
prompt="A lighthouse on a cliff at dusk, volumetric fog",
n=1,
size="1024x1024",
)
print(img.data[0].url)
# Aspect ratio + quality tier + style preset
img = client.images.generate(
model="sunburst-2.5",
prompt="A lighthouse on a cliff at dusk, volumetric fog",
n=2,
extra_body={"aspect_ratio": "16:9", "quality": "2K", "style": "cinematic"},
)Edit
from openai import OpenAI
client = OpenAI(base_url="https://fzcraft.pikonox.com/v1", api_key="fz_live_...")
img = client.images.edit(
model="sunburst-2.5",
image=open("lighthouse.png", "rb"),
prompt="Same scene, but in heavy snowfall",
n=1,
size="1024x1024",
)
print(img.data[0].url){
"created": 1763116800,
"data": [
{ "url": "https://fzcraft.pikonox.com/files/…/a1b2c3.png" },
{ "url": "https://fzcraft.pikonox.com/files/…/d4e5f6.png" }
]
}Images are kept for 48 hours
Generated images, and their entries in Image Studio history, are deleted automatically 48 hours after they are created. Download anything you want to keep, or requestresponse_format: "b64_json" to receive the image bytes directly. Your billing and usage history are not affected.Pricing & wallet
The price of n images at the requested quality is held from the image wallet when the request starts. You're charged only for images that come back; the rest is returned straight away. If the wallet can't cover the hold, the request fails with 402 insufficient_image_balance — top up the image wallet from Billing.
Models list
GET https://fzcraft.pikonox.com/v1/models lists every enabled model with its type, capabilities, context length and whether your current plan can use it (available_on_your_plan). Calling a model your plan doesn't include returns 403 model_not_in_plan.
from openai import OpenAI
client = OpenAI(base_url="https://fzcraft.pikonox.com/v1", api_key="fz_live_...")
for m in client.models.list():
extra = m.model_extra or {}
print(m.id, extra.get("type"), extra.get("available_on_your_plan")){
"object": "list",
"data": [
{
"id": "deepseek-v4.1-flash",
"object": "model",
"created": 1763116800,
"owned_by": "DeepSeek",
"name": "DeepSeek V4.1 Flash",
"type": "chat",
"capabilities": ["reasoning", "vision", "tools", "streaming", "json"],
"context_length": 1000000,
"max_output_tokens": 65536,
"available_on_your_plan": true
}
]
}Available right now
Anthropic Messages API
POST https://fzcraft.pikonox.com/v1/messages speaks Anthropic's Messages format, so the official Anthropic SDKs and tools built on them — like Claude Code — work with the same key. It isn't limited to Claude: every chat model in the catalog can be called this way, and every OpenAI model can be called through /chat/completions.
import os
from anthropic import Anthropic
client = Anthropic(
base_url="https://fzcraft.pikonox.com", # the SDK adds /v1/messages
api_key=os.environ["API_KEY"],
)
message = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Explain server-sent events in one sentence."}],
)
print(message.content[0].text){
"id": "msg_9xK2bQ7mW4tR1yZ8cV3nL6pD",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-5-5",
"content": [
{ "type": "text", "text": "Server-sent events keep one HTTP response open so the server can push updates the moment they're ready." }
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": { "input_tokens": 24, "output_tokens": 23, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0 }
}Streaming
Set "stream": true to receive Anthropic server-sent events. Errors use Anthropic's shape: {"type":"error","error":{"type":"rate_limit_error","message":"…"}}.
event: message_start
data: {"type":"message_start","message":{"id":"msg_…","role":"assistant","model":"claude-sonnet-5-5","content":[],"usage":{"input_tokens":24,"output_tokens":1}}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Server-sent events"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":23}}
event: message_stop
data: {"type":"message_stop"}Claude Code
Point Claude Code at FZ-craft with two environment variables, then pick the models it should use. The base URL is the site address — without /v1, because Claude Code adds it.
export ANTHROPIC_BASE_URL="https://fzcraft.pikonox.com"
export ANTHROPIC_AUTH_TOKEN="fz_live_..."
# Which models Claude Code should use (any chat model id from the catalog works)
export ANTHROPIC_MODEL="claude-sonnet-5-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-5-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-5-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4.1-flash" # quick background tasks
claudeChoosing models
ANTHROPIC_MODEL is the main model. Claude Code also sends small background requests (titles, summaries) to the "haiku" model — set ANTHROPIC_DEFAULT_HAIKU_MODEL to a fast, cheap model so they don't use a model that's under maintenance. Any chat model works, including non-Claude ones like deepseek-v4.1-flash. On the Free plan, use the free models (deepseek-v4.1-flash and glm-5.3) for all of them.Other coding tools
Cursor, Cline, Roo Code, Kilo Code, opencode and most other tools have an "OpenAI-compatible" provider option. Choose it, then enter:
Rate limits & quotas
Requests are limited per minute (a sliding 60-second window). Your plan sets the limit for the whole account; a key can have a lower cap of its own. Every response carries the current state in headers:
Separately from speed limits, usage is capped by quota:
429 vs 402
429 means slow down or you're out of tokens — checkerror.code. Only rate_limit_exceeded is worth retrying (after retry-after); insufficient_quota needs a bigger plan or a 24h pass.402 is about money: the key's spend cap or the image wallet. Retrying won't help until you raise the cap or top up.HTTP/1.1 429 Too Many Requests
x-ratelimit-limit-requests: 60
x-ratelimit-remaining-requests: 0
x-ratelimit-reset-requests: 12s
retry-after: 12
{
"error": {
"message": "Rate limit reached: 60 requests per minute. Upgrade your plan for higher limits.",
"type": "rate_limit_error",
"param": null,
"code": "rate_limit_exceeded"
}
}import time
import openai
from openai import OpenAI
client = OpenAI(base_url="https://fzcraft.pikonox.com/v1", api_key="fz_live_...")
def create_with_retry(**kwargs):
for attempt in range(5):
try:
return client.chat.completions.create(**kwargs)
except openai.RateLimitError as e:
if e.code != "rate_limit_exceeded":
raise # out of tokens or a key limit: retrying won't help
wait = float(e.response.headers.get("retry-after", 2 ** attempt))
time.sleep(wait)
raise RuntimeError("Still rate limited after 5 attempts")The official SDKs also retry 429 and 5xx responses a couple of times by default; the helper above adds rate-limit-aware waits.
Errors
Errors use the OpenAI shape, so SDK exception types work unchanged. type is the broad category, code the specific reason, and param names the offending field when there is one.
{
"error": {
"message": "This API key is missing the 'images' scope.",
"type": "permission_error",
"param": null,
"code": "missing_scope"
}
}If the model itself rejects a request (for example the prompt exceeds its context window), you get its 4xx status and message with the same error shape.
Billing
Token usage is covered by plans instead of per-request charges. See current prices on the pricing page.
- Plans — every account has one monthly plan (Free by default). It includes a token allowance that refreshes every 30 days, a requests-per-minute limit and a model access level (free models, all models, or all models plus early access). Paid plans are billed monthly or yearly; yearly plans still refresh tokens every 30 days.
- What counts — input tokens + output tokens (including reasoning). Cached input tokens count at 10%. Embeddings count input tokens only.
- 24h passes — for accounts on the Free plan: a block of tokens for 24 hours with no subscription. Pass tokens are used first, then the free allowance, then bonus tokens from rewards. While a pass is active you get its higher rate limit and model access. Passes can't be added to an active paid monthly plan — upgrade the plan instead.
- Balance — your main USD balance pays for plans and passes, and for auto-renewal when a term ends. If auto-renew is off or the balance is too low, you drop back to Free.
- Image wallet — a separate balance used only for images, charged per image by model and quality tier.
- Changes & refunds — upgrading credits the unused part of your current paid plan. Your first paid monthly plan can be refunded to your balance within 24 hours.
Payments
Add funds from Billing → Balance. A payment can top up your main balance, top up the image wallet, or pay for a plan directly.
- Binance Pay and BEP-20 are verified automatically. For on-chain transfers, send the exact amount shown at checkout, including the cents — it ties your transfer to your order. Credit lands once the transaction is confirmed.
- JazzCash, Easypaisa and bank transfer are paid in PKR at the rate shown at checkout, then reviewed by our team. You're notified when the payment is approved or rejected.
- Unpaid orders expire — after 2 hours for automatic methods and 72 hours for manual ones. Minimum amounts are shown at checkout.
Terms
- Use the API lawfully, follow the usage policies of the models you call, and don't use it to build abusive, deceptive or harmful products.
- You're responsible for your API keys and for all usage made with them. Don't share or resell keys.
- Service is provided as-is. We aim for high availability but don't guarantee uptime, and model availability can change.
- Payments buy plans, passes and wallet credit. They're non-refundable except as described under Billing.
- We may suspend accounts that break these terms or harm the service. We may update these terms and will note changes here.

