Text Generation and Prompting

Learn how to prompt a model to generate text using the AvalAI API. AvalAI provides access to various large language models capable of generating diverse text responses—like code, mathematical equations, structured JSON data, or human-like prose.

This guide primarily uses examples compatible with OpenAI's Responses API structure, which AvalAI supports.

Basic Text Generation

Generate text from a simple prompt:

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.5",
    instructions="You are a helpful assistant.",
    input="Write a one-sentence bedtime story about a unicorn.",
)

print(response.output_text)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const response = await client.responses.create({
  model: "gpt-5.5",
  instructions: "You are a helpful assistant.",
  input: "Write a one-sentence bedtime story about a unicorn.",
});

console.log(response.output_text);

Bash

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "instructions": "You are a helpful assistant.",
    "input": "Write a one-sentence bedtime story about a unicorn."
  }'

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	payload := map[string]any{
		"model":        "gpt-5.5",
		"instructions": "You are a helpful assistant.",
		"input":        "Write a one-sentence bedtime story about a unicorn.",
	}

	body, err := json.Marshal(payload)
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", "https://api.avalai.ir/v1/responses", bytes.NewBuffer(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AVALAI_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	responseBody, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}

	fmt.Println(string(responseBody))
}

PHP

<?php

$apiKey = getenv('AVALAI_API_KEY');

$payload = [
    'model' => 'gpt-5.5',
    'instructions' => 'You are a helpful assistant.',
    'input' => 'Write a one-sentence bedtime story about a unicorn.',
];

$ch = curl_init('https://api.avalai.ir/v1/responses');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

The response object contains an output array with the content generated by the model. A simple text response might look like this:

{
  "id": "resp_...",
  "object": "response",
  // ... other fields

  "output": [
    {
      "id": "msg_...",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Under the soft glow of the moon, Luna the unicorn danced through fields of twinkling stardust, leaving trails of dreams for every child asleep.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": { ... }
}

Important Note: The output array can contain multiple items, including tool calls or reasoning data, especially with newer models. Do not assume the primary text output is always at output[0].content[0].text. Use SDK helpers like output_text if available, or parse the output array carefully.

You can also generate structured data using Structured Outputs.

Responses-First Workflow

For new text-generation features, prefer /v1/responses when the target model and AvalAI route support it. Keep /v1/chat/completions for stable legacy integrations or provider routes that still expose only the chat schema.

Use this migration map when moving an existing chat flow:

Chat Completions	Responses API
messages	input string or input message array
system message	instructions or a developer message
choices[0].message.content	SDK output_text helper or parsed output items
Resend full messages history	previous_response_id when supported, or a compact app-managed history
stream: true chunks	stream: true semantic SSE events

Migration checklist for AvalAI apps:

• Re-send durable application rules every turn as instructions or developer content; previous instructions are not automatically retained when you chain turns with previous_response_id.
• Treat previous_response_id as a state-management helper, not a free context window. Previous chain context can still count toward billable input tokens, so summarize older turns when conversations grow.
• Parse output defensively because Responses can include text, reasoning, tool calls, or other items in one response.
• If a hosted OpenAI tool is not enabled on your AvalAI model route, use supported alternatives such as function calling, your own retrieval layer, /v1/search, or the Files API where enabled.

API Controls Beyond The Prompt

OpenAI's latest guidance for reasoning models treats prompt wording and API configuration as one system. When the selected AvalAI model and route support these fields, tune them before rewriting a long prompt:

Control	Use it when	Practical default
reasoning.effort	The task needs planning, code review, multi-step synthesis, or careful tradeoffs.	Start with low or medium; use high/xhigh only after evals show quality gains worth the latency and token cost.
text.verbosity	You need compact UI text, a richer explanation, or a fixed output size.	Set explicit budgets such as “3 bullets,” “under 120 words,” or “JSON only.”
text.format / schemas	Downstream code needs reliable fields.	Use Structured Outputs instead of describing JSON shape only in prose.
prompt_cache_key	Many requests share the same long instructions, policy, examples, or schema.	Keep stable content at the beginning and user-specific context near the end; track cached tokens in usage.
previous_response_id or returned output items	You need multi-turn state.	Use previous_response_id when retention is acceptable; replay returned output items for stateless or stricter retention flows.

For tool-heavy workflows, put operational guidance in tool descriptions: what the tool does, when to call it, required inputs, side effects, retry safety, and common error modes. Do not add the current date to every prompt by default; add date or timezone context only when the business rule depends on a user-local date, policy-effective date, or non-UTC reference.

Message Roles and Instructions

You can guide the model's behavior using the instructions parameter or different message roles within the input array.

• instructions Parameter: Provides high-level guidance (tone, goals, examples) that takes priority over input prompts for the current request. It does not persist across turns in a conversation managed with previous_response_id.

# Example using instructions parameter with AvalAI
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)
response = client.responses.create(
    model="gpt-5.5",
    instructions="Talk like a pirate.",
    input="Are semicolons optional in JavaScript?",
)
# print(response.output_text) # Access output as shown before

• Message Roles:

  • developer: Instructions from the application developer, prioritized ahead of user messages for the current request. Include these rules again on later turns when they must remain active.
  • user: Input from the end-user, weighted below developer.
  • assistant: Messages generated by the model itself.

Think of developer messages as the function definition for your application policy and user messages as the arguments supplied by the end user. This separation keeps business rules out of user-controlled text and makes prompt tests easier to write.

# Example using developer and user roles with AvalAI
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)
response = client.responses.create(
    model="gpt-5.5",
    input=[
        {"role": "developer", "content": "Talk like a pirate."},
        {
            "role": "user",
            "content": "Are semicolons optional in JavaScript?",
        },
    ],
)
# print(response.output_text) # Access output as shown before

For multi-turn conversations, see the Conversation State guide.

Output Length, Truncation, and Sampling

Responses requests should make token and truncation behavior explicit in production:

• Use max_output_tokens as an upper bound for generated output. On reasoning models it is a shared budget for visible output and hidden reasoning; if reasoning exhausts it, the response can be incomplete with incomplete_details.reason: "max_output_tokens" and no visible text. Leave headroom, inspect reasoning-token usage, and see Reasoning token budgets.
• Treat the context window as a shared budget for input, tool results, output, and reasoning. Compact long histories before they approach the model limit.
• Keep truncation disabled when dropping old context would be unsafe; the request should fail loudly instead of silently losing early instructions or evidence.
• Use truncation: "auto" only for low-risk chat histories where dropping older items is acceptable. For support, legal, finance, or agentic workflows, prefer app-managed summaries or context compaction.
• Tune temperature or top_p, not both. Keep deterministic settings for evals and regression tests.

Python

response = client.responses.create(
    model="gpt-5.5",
    instructions="Answer in at most three concise bullets.",
    input="Summarize the release notes for a product manager.",
    max_output_tokens=300,
    truncation="disabled",
    temperature=0.2,
)

print(response.output_text)

JavaScript

const response = await client.responses.create({
  model: "gpt-5.5",
  instructions: "Answer in at most three concise bullets.",
  input: "Summarize the release notes for a product manager.",
  max_output_tokens: 300,
  truncation: "disabled",
  temperature: 0.2,
});

console.log(response.output_text);

Version Prompts in Code

For production AvalAI apps, keep prompt builders in application code rather than depending on hosted prompt objects. Code-managed prompts fit normal review, typed inputs, tests, and deployment workflows.

OpenAI's current deprecation timeline says prompt creation was de-emphasized on June 3, 2026, and v1/prompts / reusable prompt objects are scheduled to shut down on November 30, 2026. Treat this as another reason to keep AvalAI prompt templates in code and send generated instructions plus input directly to /v1/responses.

• Put stable instructions builders near the feature they support.
• Use function arguments or schemas for dynamic values such as customer data, files, or task options.
• Pass the generated instructions and input directly to /v1/responses.
• Add fixtures and eval checks before changing prompts used in production.
• Roll out prompt changes with your normal release process or feature flags.

Choosing a Model

AvalAI provides access to models from various providers (OpenAI, Anthropic, Google, etc.). Consider these factors when selecting a model (specified in the model parameter):

• Capabilities: Different models excel at different tasks (reasoning, speed, cost-efficiency).
• Provider: AvalAI allows you to choose models like gpt-5.5, claude-opus-4-8, gemini-3.5-flash, etc.
• Cost vs. Performance: Larger models might be more capable but slower and more expensive. Smaller models can be faster and cheaper, and potentially fine-tuned for specific tasks.

Refer to the Models Overview for details on available models and their providers. gpt-5.5 via AvalAI is often a good starting point for OpenAI-family Responses workflows; use smaller or provider-specific models when latency or price matters more.

Prompt Engineering

Crafting effective prompts is crucial for getting desired outputs. Key principles include:

• Be Specific: Clearly define the task and expected output format.
• Provide Examples (Few-Shot Learning): Show the model input/output examples.
• Set Goals (Reasoning Models): Describe the desired outcome rather than step-by-step instructions.
• Evaluate: Use test data (Evals Guide) to measure prompt performance.

Explore our Prompt Engineering Guide for more techniques. Fine-tuning can further customize models.

Next Steps

• Structured Data: Learn about Structured Outputs.
• API Reference: Consult the Chat Completions or Responses API reference for all parameters.