Ditfa Platform API

1. 1Add credits to your wallet ($5 minimum).
2. 2Create an API key. It starts with sk-dp- and is shown only once; store it as DITFA_API_KEY.
3. 3Point any OpenAI SDK at https://gateway.ditfa.com/v1 and pick a model slug from /models.

curl https://gateway.ditfa.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DITFA_API_KEY" \
  -d '{
  "model": "openai/gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "Write a haiku about the ocean."
    }
  ]
}'

Every endpoint except GET /models needs a key, sent as a bearer token:

Authorization: Bearer sk-dp-…

Keys are stored hashed; the full key is shown once when you create it. Each key can be scoped in the dashboard:

Disable a key to pause it, or delete it to revoke it for good; request history is kept either way. Key changes take effect within a few seconds. Up to 25 keys can be active per account.

Request body

Response

A chat.completion object. id is the Ditfa generation id and model is the public slug you requested, whichever provider served it.

{
  "id": "gen-3f1c2a7e-8b4d-4c1e-9a0f-5d6e7b8c9d0e",
  "object": "chat.completion",
  "created": 1793318400,
  "model": "openai/gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Waves fold into foam…"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 17,
    "total_tokens": 31
  }
}

Response headers

curl https://gateway.ditfa.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DITFA_API_KEY" \
  -d '{
  "model": "openai/gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "Write a haiku about the ocean."
    }
  ]
}'

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"openai/gpt-4o-mini","choices":[{"index":0,"delta":{"role":"assistant","content":"Waves"}}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"openai/gpt-4o-mini","choices":[{"index":0,"delta":{"content":" fold"}}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"openai/gpt-4o-mini","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"openai/gpt-4o-mini","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":17,"total_tokens":31}}

data: [DONE]

• The last chunk before [DONE] carries usage with an empty choices array. The gateway always requests it, so you do not need stream_options. Guard against empty choices when reading deltas.
• Chunk ids come from the provider. Use the x-ditfa-generation-id response header to look the request up later.
• If you disconnect mid-stream, you pay only for the output already delivered. A stream that delivered nothing is not charged.

curl https://gateway.ditfa.com/v1/key \
  -H "Authorization: Bearer $DITFA_API_KEY"

{
  "data": {
    "limit": 50,
    "limit_period": "month",
    "usage": 12.4,
    "limit_remaining": 37.6,
    "allowed_models": []
  }
}

Amounts are USD. limit and limit_remaining are null when the key has no spend limit; usage is then the key's lifetime spend.

{
  "data": {
    "balance": 24.5,
    "reserved": 0.02,
    "available": 24.48
  }
}

reserved is held for requests in flight; available = balance − reserved is what new requests can use.

{
  "data": {
    "id": "gen-3f1c2a7e-8b4d-4c1e-9a0f-5d6e7b8c9d0e",
    "model": "openai/gpt-4o-mini",
    "created_at": "2026-10-30T09:12:44.512Z",
    "status": "ok",
    "streamed": true,
    "tokens_prompt": 14,
    "tokens_completion": 17,
    "tokens_cached": 0,
    "tokens_reasoning": 0,
    "total_cost": 0.000013,
    "latency_ms": 812,
    "ttft_ms": 241
  }
}

total_cost is the USD amount charged. status is ok, error or canceled; ttft_ms (time to first token) is set for streams. Usage is written once the request finishes, so query it after the response or stream ends. Any key of the same account can read it.

You pay per token in USD from a prepaid wallet. Prompt tokens are billed at the input rate, cached prompt tokens at the cache-read rate when the model has one, and output tokens (including reasoning tokens) at the output rate, plus any fixed per-request fee.

How a request is charged

1. Reserve. Before calling the model, the gateway holds an upper bound: the estimated prompt plus the maximum output (max_tokens, else 16,384, capped by the model). If available credits or the key's limit cannot cover it, you get 402.
2. Settle. When the response ends, the real usage is charged and the rest of the hold is released.
3. Release. A failed request releases the whole hold. You are never charged for 4xx errors or for 502s.

Top-ups are $5 to $1,000 each and credits never expire. A low-balance email alert can be set in the settings.

A model can be served by several providers. The gateway tries up to three of them in priority order and moves providers that are currently failing for several users to the back of the line.

• If a provider times out, returns 408, 429 or 5xx, or cannot be reached, the next one is tried automatically. Nothing has been sent to you yet, so fallback is invisible.
• A 400 from a provider means the request itself was rejected; it is not retried elsewhere.
• You are billed at the rate of the provider that answered. The catalog shows the lowest available price; /generation shows exactly what you paid.
• The provider policy on a key or the account (verified providers only, no prompt logging) removes providers from routing. If none are left you get 403 no_allowed_provider.

{
  "error": {
    "message": "Insufficient credits. Top up your wallet at https://platform.ditfa.com/credits.",
    "type": "payment_required",
    "code": "insufficient_credits",
    "param": null
  }
}

Handling errors

Retry only 429 and 5xx, with exponential backoff and jitter, and honour retry-after. Treat 401, 402, 403 and 404 as configuration problems: retrying will not help.

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://gateway.ditfa.com/v1',
  apiKey: process.env.DITFA_API_KEY,
  maxRetries: 3, // retries 429 and 5xx with backoff, honouring retry-after
});

try {
  const completion = await client.chat.completions.create({
    model: 'openai/gpt-4o-mini',
    messages: [{ role: 'user', content: 'Hello' }],
  });
  console.log(completion.choices[0].message.content);
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    switch (error.code) {
      case 'insufficient_credits':
      case 'key_limit_reached':
        // Not retryable: alert someone to top up or raise the key limit.
        break;
      case 'model_not_found':
      case 'model_not_allowed':
        // Fix the model slug or the key's allowed models.
        break;
      default:
        console.error(error.status, error.code, error.message);
    }
  }
  throw error;
}

Need a higher request rate? Contact us with your expected volume.

HTTP-Referer: https://your-app.example
X-Title: Your App

Referer is accepted when HTTP-Referer is absent. Only the origin of the referer is ever shown publicly, never its path or query. Both values also appear in your own request log.

• Use one key per app or environment, each with its own spend limit, so a leak or a bug has a ceiling.
• Add an IP allowlist for keys used from fixed servers, and an expiry for temporary keys.
• Restrict production keys to the models you actually use, so a typo cannot route to a much pricier model.
• Log x-ditfa-generation-id with your own request ids; it makes cost questions and support tickets quick to answer.
• Check GET /credits from a cron job or set a low-balance alert so production never hits insufficient_credits.

Host your own model? Sell it to every Ditfa Platform developer at your own price through the Ditfa Provider Program.Become a provider