Flamify REST API.

Overview

Flamify exposes a JSON REST API for text generation and a binary response endpoint for speech. Send requests from your backend so credentials never reach a browser or mobile bundle.

Quick start

Copy your API URL and bearer token from the dashboard, then store both as server-side environment variables.

export FLAMIFY_BASE_URL="YOUR_DASHBOARD_API_URL"
export FLAMIFY_API_TOKEN="YOUR_DASHBOARD_BEARER_TOKEN"

curl "$FLAMIFY_BASE_URL/chat/completions" \
  --request POST \
  --header "Authorization: Bearer $FLAMIFY_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "flamify_model_l1",
    "messages": [
      {"role": "user", "content": "Give me three ideas for a calm evening."}
    ]
  }'

Authentication

Every API request must include a bearer token generated in the Flamify dashboard. Send it in the Authorization header.

Authorization: Bearer YOUR_DASHBOARD_BEARER_TOKEN

• Keep tokens in a secret manager or protected server environment variable.
• Never expose a token in client-side code, source control, logs, or error messages.
• Create separate credentials for development and production, and rotate any token that may have been exposed.

API conventions

A few shared conventions apply across the API. Following them keeps integrations portable between development and production environments.

Chat completions

Create a model response from a conversation. Pass the model ID and an ordered list of messages.

Response object

The generated message is returned in choices[0].message. Use finish_reason to confirm why generation stopped, and record usage when it is present.

{
  "id": "chatcmpl_7f42c9",
  "object": "chat.completion",
  "created": 1789812000,
  "model": "flamify_model_l1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Start with a quiet walk, cook something simple, and finish with a screen-free hour."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 24,
    "total_tokens": 42
  }
}

Structured responses

Use response_format when your application needs predictable JSON rather than free-form text. Provide a JSON Schema and Flamify will constrain a compatible chat model to that shape, reducing missing fields, unexpected keys, and invalid values.

The field follows the OpenAI API format, so existing schemas and integration patterns are easy to reuse. See the OpenAI Structured Outputs guide and introduction to Structured Outputs for additional schema patterns.

Request example

curl "$FLAMIFY_BASE_URL/chat/completions" \
  --request POST \
  --header "Authorization: Bearer $FLAMIFY_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "flamify_model_l1",
    "messages": [
      {
        "role": "user",
        "content": "Classify this message: I cannot sign in and need help today."
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "support_request",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "topic": {"type": "string"},
            "priority": {
              "type": "string",
              "enum": ["low", "medium", "high"]
            }
          },
          "required": ["topic", "priority"],
          "additionalProperties": false
        }
      }
    }
  }'

Implementation notes

• Choose a model whose capabilities include supportsResponseSchema: true.
• Use strict: true when the response must follow the supplied schema exactly.
• Declare every expected field in required and set additionalProperties to false for the most reliable output.
• Schema support is a subset of JSON Schema. Keep schemas focused and validate the parsed response in your application.
• Handle refusals and interrupted generations before reading the structured payload.

Models

Inspect model capabilities before enabling optional API features. Structured responses are available only when supportsResponseSchema is true.

curl "$FLAMIFY_BASE_URL/models" \
  --header "Authorization: Bearer $FLAMIFY_API_TOKEN"

The response contains the models available to the authenticated account. Use each model's capability metadata when deciding which controls to expose in your product.

{
  "id": "flamify_model_l1",
  "type": "text",
  "object": "model",
  "created": 1726869022,
  "owned_by": "flamify.ai",
  "model_spec": {
    "availableContextTokens": 32768,
    "capabilities": {
      "supportsFunctionCalling": true,
      "supportsResponseSchema": true,
      "supportsWebSearch": true
    }
  }
}

Text-to-speech

Turn text into spoken audio with a Flamify speech model. Select a compatible voice, send up to 4,096 characters to /audio/speech, and write the binary response directly to an audio file.

Available models

• tts-orpheus
• tts-minimax-speech-02-hd
• tts-kokoro

Request shape

Request example

curl "$FLAMIFY_BASE_URL/audio/speech" \
  --request POST \
  --header "Authorization: Bearer $FLAMIFY_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "tts-orpheus",
    "voice": "YOUR_VOICE_ID",
    "input": "Welcome to Flamify.",
    "response_format": "mp3"
  }' \
  --output speech.mp3

The endpoint returns audio bytes rather than JSON. Match the output filename extension to the requested response_format.

Errors

Unsuccessful requests return an HTTP status that identifies the failure category. Log the status and request identifier when available, but never log the bearer token.

{
  "error": {
    "message": "The messages field is required.",
    "type": "invalid_request_error",
    "param": "messages",
    "code": "invalid_request"
  }
}

Production checklist

Before sending production traffic, make failure handling and observability part of the integration rather than an afterthought.

• 01Set explicit timeouts.Bound connection and response time so a slow upstream request cannot exhaust your own worker pool.
• 02Retry selectively.Retry rate limits and temporary service errors with exponential backoff and random jitter. Do not automatically retry validation or authentication failures.
• 03Validate at the boundary.Parse and validate structured responses before passing them to business logic, even when strict schema mode is enabled.
• 04Log useful signals.Capture endpoint, model, status, latency, and request identifiers when available. Exclude bearer tokens and sensitive prompt content.
• 05Expect model changes.Read the model catalog at runtime or during deployment, and degrade gracefully when an optional capability is unavailable.

Security

• Call Flamify only from infrastructure you control.
• Use HTTPS for every request and reject certificate errors.
• Redact tokens and sensitive prompt content from application logs.
• Apply your own authentication and authorization before accepting requests from client applications.
• Rotate credentials immediately if exposure is suspected.