The DeepFA AI API,
OpenAI-compatible

POST /v1/messages

Anthropic's Messages API shape, for Claude models; the route Claude Code calls with ANTHROPIC_BASE_URL set to https://deepfa.ir/api. The body goes through unchanged: block-form system, cache_control, thinking and tools, with the anthropic-beta and anthropic-version headers. A stream comes back event by event in order, and errors are in Anthropic's shape. Dated ids such as claude-haiku-4-5-20251001 and the [1m] suffix are accepted.

A few things are removed, because each costs more than the token rates in the price table: speed (fast mode), inference_geo and service_tier, and the server-side web search and code execution tools that Anthropic bills per use. POST /v1/messages/count_tokens counts a request's tokens free of charge. Models other than Claude are served by /v1/chat/completions.

POST /v1/responses

OpenAI's Responses API shape, for OpenAI models; the only shape Codex speaks (wire_api = "responses"). input items, reasoning items with their encrypted content, and function, custom and shell tools pass through unchanged. A stored response (the default, unless "store": false) is kept for thirty days, and its previous_response_id works for the same account only. The conversation parameter is not supported.

Removed: service_tier, background, and the hosted tools billed per use (web and file search, code interpreter, image generation, computer use and remote MCP).

Retired model names

A request naming a model that has been replaced, such as gpt-5.6-luna, is answered by its replacement (gpt-6-luna) at its price, and the key's owner is told once by email and in the dashboard. The names are listed on the Models tab of the API page.

POST /v1/images/generations — pictures come back as b64_json (base64 PNG), and only the pictures actually made are charged.

{
  "model": "flux-schnell",
  "prompt": "A lighthouse at dawn, watercolour",
  "n": 2,
  "size": "1536x1024"
}

POST /v1/images/edits

Image to image, sent as multipart/form-data as with OpenAI: one to four pictures with a description, and the new picture comes back as b64_json. A picture costs the model's price; where the supplier bills every input picture, each one adds the credits_per_input_image shown by GET /v1/models.

curl https://deepfa.ir/api/v1/images/edits \
  -H "Authorization: Bearer $DEEPFA_API_KEY" \
  -F model=flux-3 \
  -F "image[]=@product.png" \
  -F "prompt=Place this bottle on a marble counter in soft morning light"

POST /v1/audio/speech

Returns the audio file itself, charged per character.

POST /v1/audio/transcriptions

Sent as multipart/form-data; charged per started minute.

Making a video takes minutes, so it is a job: POST /v1/videos starts it and at once returns its id with the status queued; poll GET /v1/videos/{id} every few seconds until the status moves from in_progress to completed (with the file's url) or failed; GET /v1/videos/{id}/content redirects to the finished file (302), or answers 409 if it is not ready. The credit is charged when the job is accepted, and given back in full if it fails.

Models and the lengths they make

curl https://deepfa.ir/api/v1/videos \
  -H "Authorization: Bearer $DEEPFA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "grok-imagine-15",
  "prompt": "A paper boat sailing down a rainy street",
  "seconds": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}'

{
  "id": "t_48213",
  "object": "video",
  "model": "grok-imagine-15",
  "kind": "text_to_video",
  "status": "queued",
  "seconds": 5,
  "created_at": 1790443124
}

A podcast is a job, like a video: POST /v1/podcasts takes the script and returns an id such as p_123 at once; ask GET /v1/podcasts/{id} until its status is completed, then fetch the audio from GET /v1/podcasts/{id}/content (?what=transcript for the text, ?what=srt for subtitles). The voices are made by gemini-3.8-flash-lite-tts; you pay once, after the whole podcast exists, by the characters read and at the rate of /v1/audio/speech for this model - nothing is charged if it fails. The script is yours to bring (write it with /v1/chat/completions).

At most 12,000 characters a podcast (about twenty minutes) and three podcasts at once per account. A podcast made through the API also appears in the AI Podcast tool.

curl https://deepfa.ir/api/v1/podcasts \
  -H "Authorization: Bearer $DEEPFA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language":"en","voices":["Kore","Puck"],"turns":[{"speaker":1,"text":"Hi everyone, welcome! "},{"speaker":2,"text":"Glad to be here.","style":"warmly"}]}'

{"id":"p_123","object":"podcast","model":"gemini-3.8-flash-lite-tts","status":"queued","progress":0}

For thousands of requests, in the shape of OpenAI's Batch API and with the same libraries: write the requests in a JSONL file (one a line), upload it with POST /v1/files and purpose=batch, start it with POST /v1/batches, ask GET /v1/batches/{id} until its status is completed, and download the answers from GET /v1/files/{output_file_id}/content. The requests run in the background within 24 hours, without the key's rate limit, each charged exactly as the same live request would be and within the key's daily and monthly ceilings.

{"custom_id": "news-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-6-luna", "messages": [{"role": "user", "content": "..."}]}}
{"custom_id": "news-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-6-luna", "messages": [{"role": "user", "content": "..."}]}}

curl https://deepfa.ir/api/v1/files -H "Authorization: Bearer $DEEPFA_API_KEY" -F purpose=batch -F file=@requests.jsonl
curl https://deepfa.ir/api/v1/batches -H "Authorization: Bearer $DEEPFA_API_KEY" -H "Content-Type: application/json" \
  -d '{"input_file_id": "file-...", "endpoint": "/v1/chat/completions", "completion_window": "24h"}'

Instead of asking again and again, give an https address on the Connect tab of the API page. When a long job ends an event is posted to it, and tried again for about a day until your server answers 2xx (after 1, 5 and 30 minutes, then 2, 6 and 15 hours). The body names the job only; fetch the result with your key.

{"id": "evt_...", "object": "event", "type": "video.completed", "created_at": 1793000000,
 "data": {"id": "t_123", "object": "video", "status": "completed"}}

Checking the signature

Each post carries the three Standard Webhooks headers OpenAI's own webhooks use: webhook-id, webhook-timestamp and webhook-signature (v1, followed by the base64 HMAC-SHA256 of "id.timestamp.body" under the signing secret's bytes). The signing secret (whsec_...) is on the same Connect tab; the Standard Webhooks libraries and webhooks.unwrap in OpenAI's official SDK verify it.

# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook

event = Webhook("whsec_...").verify(request_body, request_headers)  # raises if forged

GET /v1/models

Lists only the models your plan and key allow, each with a pricing object in credits. Text models: input_per_million_tokens, output_per_million_tokens, and where they apply cached_input_per_million_tokens and cache_write_per_million_tokens. Other models: credits per credits_per (image, character, minute, video or second); for a video, seconds and resolution name the clip that price is for. Always the price actually charged.

GET /v1/balance

What this key can spend, at no charge. available is the account credit the API can draw on, and pockets splits it in the order it is spent: API credit, plan credit, prepaid credit. key shows this key's daily and monthly ceilings with what has gone against them, and spendable is what the key can spend right now: the balance narrowed by the nearest ceiling. On an unlimited account, unlimited is true and available is null. For a team member whose owner opened the API to them, pockets.team is their share of the team's credit (within their monthly limit), counted in available.

curl https://deepfa.ir/api/v1/balance -H "Authorization: Bearer $DEEPFA_API_KEY"

{
  "object": "balance",
  "unit": "credits",
  "unlimited": false,
  "available": 6500,
  "pockets": {"api": 5000, "plan": 1200, "prepaid": 300},
  "key": {
    "name": "production",
    "rpm_limit": 60,
    "daily":   {"limit": 100,  "spent": 30, "remaining": 70},
    "monthly": {"limit": null, "spent": 30, "remaining": null}
  },
  "spendable": 70
}

Every error comes back in the standard OpenAI shape, with code the same as type; param names the field at fault. On /v1/messages it comes back in Anthropic's shape instead.

{
  "error": {
    "message": "The model \"gpt-9\" is not available.",
    "type": "model_not_found",
    "param": "model",
    "code": "model_not_found"
  }
}

Limits

• Requests a minute per key: 60 by default; set it anywhere from 1 to 6,000 when you make or edit the key in the panel. Beyond it, 429 with a Retry-After header.
• An optional daily and monthly credit ceiling per key, set in the panel; GET /v1/balance shows what is left of it.
• Optional on each key: allowed IP addresses (IPv4, IPv6 or a CIDR range), the groups of endpoints it may call, an end date, and switching it off for a while.
• At most three agent runs at once per account.
• Transcription files up to 25 MB; speech input up to 4,096 characters; up to 10 pictures a request; video edits of 1 to 120 seconds.
• Each request's cost comes back in the x-deepfa-credits header and its id in x-deepfa-request-id; quote that id when you contact support.

Optional headers

• X-DeepFA-Tag: a label of up to 64 characters for each request (a project, a department, one of your customers); the usage page and its Excel sheet break the spending down by it. Percent-encode a non-Latin label, since most libraries take only Latin letters in a header.
• Idempotency-Key: send the same request again with the same key within a day (after a dropped connection, say) and the first answer comes back with Idempotent-Replayed: true; the request is not run or charged again. A streamed answer is not played back; its key only keeps it from running twice.

For tools and monitoring

• The whole API described in OpenAPI 3.1, to load into Postman or Insomnia or generate a client from: /api/openapi.json
• Each part of the API now and over the last ninety days: the status page and, for your monitoring, /api/status.json