Code Generation

Use AvalAI models to write, review, refactor, and debug code through OpenAI-compatible APIs.

OpenAI’s official code-generation guidance recommends the Responses API for API-based coding workflows and Codex for agentic software engineering. In AvalAI, use the same pattern with AVALAI_API_KEY and https://api.avalai.ir/v1: start with /v1/responses for new code workflows, keep Chat Completions for existing integrations, and use Setup Codex when you want an agent inside your terminal or editor.

Choosing a Coding Workflow

Workflow	Recommended path	Notes
One-shot code generation or debugging	/v1/responses	Use instructions, concise input, and response.output_text.
Existing chat-based code assistant	/v1/chat/completions	Keep it if the app is stable; migrate flow-by-flow when you need Responses items, reasoning, or tools.
Repository editing, tests, and review	Codex with AvalAI as provider	See Setup Codex.
Large refactors	Responses plus your own retrieval/tool loop	Send relevant files only; preserve response.output items when tools or reasoning are involved.

Apply Patch and Skill-Aware Agents

OpenAI documents apply_patch as a Responses/Agents SDK tool that returns structured apply_patch_call items for file create, update, and delete operations. In AvalAI, treat this as a route-dependent hosted editing capability, not a general guarantee. If your selected route does not explicitly support tools: [{"type": "apply_patch"}], ask the model for a normal unified diff and apply it in your own review workflow, Codex session, or backend patch harness.

When you do build an apply-patch harness, keep the model responsible for proposing diffs and keep your application responsible for enforcement:

• restrict paths to an allowlisted workspace and reject directory traversal;
• apply patches in a scratch copy or transaction when possible;
• return one apply_patch_call_output per call_id with status: "completed" or status: "failed" plus a short error;
• run tests, linters, or git diff --check after each editing round and feed failures back as normal input;
• require human approval for deletes, dependency changes, generated binaries, migrations, or broad rewrites.

OpenAI Skills are versioned bundles with a SKILL.md manifest that can guide shell or coding agents. For AvalAI applications, treat Skills as privileged instructions and code: review them before use, map them to specific product workflows, and do not let end users attach arbitrary Skills from an open catalog. If hosted Skills are not available on your route, keep the same knowledge in your own repo docs, prompt templates, tool descriptions, or local runtime files.

Code Task Brief Template

OpenAI's code-generation examples keep the model call simple: task input, optional system-level instructions, and a coding model with higher reasoning effort. For AvalAI apps, make that input repeatable by packaging every request as a short task brief:

• Goal: one sentence describing the change, bug, or review question.
• Allowed files: exact paths the model may inspect or edit.
• Context: only the relevant source, docs excerpts, stack traces, or API contracts.
• Constraints: non-goals such as “do not change public APIs,” “no new dependencies,” or “keep RTL text intact.”
• Expected output: diagnosis, unified diff, replacement file, test plan, or review notes.
• Verification: the command a human or agent should run after applying the patch.

Example input for /v1/responses:

Goal: Fix the empty-state bug in the billing table.
Allowed files: src/components/BillingTable.tsx, tests/BillingTable.test.tsx
Context: The table renders nothing when invoices=[]; expected copy is "No invoices yet".
Constraints: Keep existing props and CSS classes. Do not add dependencies.
Expected output: Short diagnosis, minimal unified diff, and targeted test command.
Verification: npm test -- BillingTable.test.tsx

Use this brief as input and keep durable behavior in instructions. When the model returns tool calls, reasoning items, or multiple output items, read response.output; use response.output_text only for the final human-readable text.

Model Selection

Use a model that matches the complexity of the task:

• gpt-5.5: strong default for coding plus general reasoning.
• gpt-5.3-codex: optimized for Codex-style agentic coding workflows.
• claude-opus-4-8: useful for large codebases and long-context reasoning.
• kimi-k2.7-code: strong coding-focused alternative when you want provider diversity.

Check Model Details and provider pages before shipping; model availability, context length, and route support can vary.

Frontend and Docs-Grounded Agents

OpenAI's code-generation guide calls out modern GPT coding models as especially strong for frontend development when they run inside an agent harness. In AvalAI, make UI generation safer by giving the model a narrow design brief instead of a vague request:

• name the framework, package manager, component library, and files that may change;
• include screenshots, CSS variables, accessibility requirements, and responsive breakpoints;
• ask for one implementation path, then run the app and compare against the visual target;
• keep user-visible text, theme tokens, and RTL/LTR requirements explicit for bilingual products.

For docs-grounded coding assistants, do not rely on the model to remember API details. Retrieve the relevant docs page, changelog, or internal convention first, then pass only the needed excerpts into /v1/responses. Ask the model to cite the excerpt it used and to mark unknown API behavior as an assumption. This is the portable AvalAI version of OpenAI's docs-agent pattern.

Responses Example

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=os.getenv("AVALAI_MODEL", "gpt-5.5"),
    instructions=(
        "You are a senior software engineer. Return a concise diagnosis, "
        "then a minimal patch suggestion. Do not invent files."
    ),
    input="Find the likely null pointer bug in this code:\\n\\n...paste code here...",
    reasoning={"effort": "high"},
)

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: process.env.AVALAI_MODEL ?? "gpt-5.5",
  instructions:
    "You are a senior software engineer. Return a concise diagnosis, then a minimal patch suggestion. Do not invent files.",
  input: "Find the likely null pointer bug in this code:\\n\\n...paste code here...",
  reasoning: { effort: "high" },
});

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 senior software engineer. Return a concise diagnosis, then a minimal patch suggestion. Do not invent files.",
    "input": "Find the likely null pointer bug in this code:\n\n...paste code here...",
    "reasoning": { "effort": "high" }
  }'

Chat Completions Fallback

Use this shape when an existing coding assistant is still built on Chat Completions or the selected model only exposes chat compatibility.

Python

import os
from openai import OpenAI

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

completion = client.chat.completions.create(
    model=os.getenv("AVALAI_MODEL", "gpt-5.5"),
    messages=[
        {"role": "system", "content": "You are a senior software engineer."},
        {
            "role": "user",
            "content": "Refactor this function for readability:\\n\\n...code...",
        },
    ],
)

print(completion.choices[0].message.content)

JavaScript

import OpenAI from "openai";

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

const completion = await client.chat.completions.create({
  model: process.env.AVALAI_MODEL ?? "gpt-5.5",
  messages: [
    { role: "system", content: "You are a senior software engineer." },
    { role: "user", content: "Refactor this function for readability:\\n\\n...code..." },
  ],
});

console.log(completion.choices[0].message.content);

Bash

curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "system", "content": "You are a senior software engineer."},
      {"role": "user", "content": "Refactor this function for readability:\n\n...code..."}
    ]
  }'

Prompting Checklist

• State the target language, framework, runtime version, and files that may change.
• Ask for a minimal patch or complete replacement file, not both.
• Include failing test output, stack traces, and exact error messages.
• For large repos, retrieve only relevant files and ask the model to list assumptions before changing code.
• For refactors, define non-goals such as “do not change public APIs” or “keep database schema unchanged.”
• For generated code, run tests and linters before shipping; treat model output as a draft.

Review, Diff, and Security Workflow

For repository work, ask the model to produce changes in a reviewable shape:

• Request a short plan before code when the task touches multiple files.
• Prefer unified diff or clearly named replacement files for patch review.
• Ask the model to explain public API changes, migration steps, and test coverage.
• Run targeted tests first, then broader tests or linters once the patch is stable.
• Treat generated code as untrusted: review dependency additions, shell commands, file paths, SQL, regexes, authentication logic, and network calls before execution.
• For security-sensitive code, ask for a threat-model pass and require the model to identify assumptions, input validation, authorization checks, and secrets-handling boundaries.

Migration Notes

• messages → input plus optional top-level instructions.
• choices[0].message.content → response.output_text.
• For tool-using coding agents, inspect response.output and preserve typed items such as reasoning, function_call, and function_call_output.
• For known-output file edits, see Predicted Outputs when you must stay on Chat Completions.

Related Guides

• Responses vs. Chat Completions
• Prompt engineering
• Function calling
• Setup Codex
• Predicted Outputs