Chat Completions

POST /v1/chat/completions принимает messages с текстом и поддерживаемыми изображениями и возвращает chat.completion либо SSE chat.completion.chunk. Нужны chat:write, доступ к модели и Idempotency-Key.

Сообщения и параметры

Поддерживаются system, user, assistant, tool; developer — для моделей, у которых эта роль указана в параметрах. Порядок сообщений и tool-call IDs сохраняется. Модель не выбирается автоматически при неизвестном ID.

В зависимости от модели доступны temperature, top_p, max_tokens / max_completion_tokens, reasoning_effort, response_format, tools, tool_choice, parallel_tool_calls, stream и stream_options.include_usage. Только n: 1. Неизвестные и неподдерживаемые поля отклоняются до оплаты.

Поток

python

import os
import uuid
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["RENDERFOX_API_KEY"],
    base_url=os.environ.get("RENDERFOX_BASE_URL", "https://api.renderfox.ru/v1"),
    max_retries=0,
)
request_key = str(uuid.uuid4())
stream = client.chat.completions.create(
    model="gpt-5.6-luna",
    messages=[{"role": "user", "content": "Объясни SSE."}],
    max_tokens=256,
    stream=True,
    stream_options={"include_usage": True},
    extra_headers={"Idempotency-Key": request_key},
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="")

Текст и аргументы инструментов передаются по мере формирования ответа. Заключительный finish_reason публикуется после учёта расхода FC. При include_usage отдельный usage-чанк имеет пустой choices. Завершение — data: [DONE].

Инструменты и JSON

Для модели с tools передайте function schema, затем верните результат в tool с тем же tool_call_id. RenderFox не исполняет клиентские инструменты. Аргументы передаются как JSON-строка; в потоке приходят фрагменты аргументов. Незавершённые/чужие IDs отклоняются.

json_schema доступен только при соответствующей capability. Скрытая цепочка рассуждений в публичный ответ не добавляется; reasoning tokens учитываются как часть usage.

Изображения и файлы

Проверьте capabilities.vision_by_protocol.chat_completions в карточке модели. Изображение передаётся блоком image_url с data URL. detail выбирается из опубликованных ограничений. RenderFox проверяет MIME по содержимому, декодирует в ограниченной памяти, удаляет EXIF и сохраняет последовательность text/image.

python

import base64
from pathlib import Path

picture = base64.b64encode(Path("image.png").read_bytes()).decode("ascii")
reply = client.chat.completions.create(
    model="gpt-5.6-luna",
    messages=[{"role":"user","content":[
        {"type":"text","text":"Опиши изображение."},
        {"type":"image_url","image_url":{
            "url":"data:image/png;base64,"+picture,"detail":"auto"
        }}
    ]}],
    max_tokens=64,
    extra_headers={"Idempotency-Key":str(uuid.uuid4())},
)
print(reply.choices[0].message.content)

Вместо url доступен поле file_id RenderFox внутри image_url. Файл должен принадлежать владельцу ключа. Внешние HTTPS адреса, локальные пути и приватные IP отклоняются до резерва и не загружаются. Поддержка изображения в Messages не означает её поддержку в Chat у каждой модели.

Usage и finish_reason

prompt_tokens включает оплачиваемый вход, включая изображения. completion_tokens включает reasoning там, где он уже входит в оплачиваемый выход. total_tokens — их сумма. Категории кэша передаются в details при наличии достоверных счётчиков. Не прибавляйте reasoning повторно.

stop завершает ответ, length означает достижение лимита, tool_calls передаёт управление приложению. Отказ по политике контента и транспортная ошибка имеют разные состояния оплаты. Проверяйте request_id и окончательный статус; не считайте любой обрыв бесплатным запросом.

Tool loop

Function schema содержит name, description и parameters. После ответа сохраните assistant message с tool_calls, выполните только разрешённые функции и добавьте tool messages с соответствующими tool_call_id. Новый turn — отдельный запрос и резерв. В stream delta.tool_calls[index] может содержать только часть arguments: собирайте JSON до завершения вызова, не исполняйте неполные аргументы.