# Agnes 2.5 Flash Source: https://wiki.agnes-ai.com/en/docs/agnes-25-flash Generally available upgrade of Agnes 2.0 Flash with improved coding capability, agent workflows, tool calling, and multimodal understanding. Agnes 2.5 Flash is a generally available language model upgraded from Agnes 2.0 Flash. It keeps the same OpenAI-compatible Chat Completions integration path while improving the experience for coding, agent workflows, tool calling, multi-turn conversations, reasoning, and image understanding. `agnes-2.5-flash` Chat Completions: `POST /v1/chat/completions`
Responses: `POST /v1/responses`
Messages: `POST /v1/messages` Generally available to users with Agnes API access. API-compatible upgrade from the deprecated `agnes-2.0-flash` model. ## Overview Agnes 2.5 Flash is designed as the next-step upgrade for developers already using Agnes 2.0 Flash. In most integrations, you only need to replace the `model` value with `agnes-2.5-flash`; the Base URL, endpoint, headers, message format, streaming format, tool-calling format, and image URL input format remain the same. The model focuses on a smoother developer experience, stronger instruction following, more stable multi-turn output, and improved code-specific capability for generation, debugging, refactoring, explanation, and agentic coding workflows. Use `agnes-2.5-flash` directly as the model name. `agnes-2.0-flash` is deprecated, so existing integrations should migrate as soon as possible. ## Core Capabilities Generate high-quality responses for conversations, applications, and business systems. Maintain context consistency across continuous interactions. Accept visual content through publicly accessible image URLs. Analyze screenshots, describe images, answer visual questions, and extract visual information. Support function calling and external tool orchestration. Improved planning, execution, context tracking, and multi-step task completion. Optimized for code generation, debugging, refactoring, explanation, and patch-style development workflows. Return responses in real time for a better interactive experience. ## Use Cases General Q\&A, productivity assistants, personal assistants, and in-app copilots. Multi-step task execution, planning, tool use, and workflow scheduling. Code generation, bug fixing, refactoring suggestions, code review, test generation, and code explanation. FAQ automation, support chatbots, and service workflow automation. Retrieval-based answers, summarization, and information extraction. Screenshot analysis, image description, visual Q\&A, and structured extraction. ## Upgrade from Agnes 2.0 Flash If you already call `agnes-2.0-flash`, the 2.5 Flash migration is intentionally small. | Item | Agnes 2.0 Flash (Deprecated) | Agnes 2.5 Flash | | - | - | - | | Endpoint | `POST /v1/chat/completions` | `POST /v1/chat/completions` | | Base URL | `https://apihub.agnes-ai.com/v1` | `https://apihub.agnes-ai.com/v1` | | Model name | `agnes-2.0-flash` | `agnes-2.5-flash` | | Message format | OpenAI-compatible `messages` | Same | | Streaming | `stream: true` | Same | | Tool calling | `tools` and `tool_choice` | Same | | Image URL input | `messages[].content[].image_url` | Same | For existing integrations, migration can usually be handled as a model-name change. Do not continue using the deprecated `agnes-2.0-flash` model as a compatibility fallback. ## API Reference ### Endpoint ```text theme={null} POST https://apihub.agnes-ai.com/v1/chat/completions ``` ### Headers ```bash theme={null} -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" ``` ### Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Model name. Use `agnes-2.5-flash`. | | `messages` | array | Yes | Conversation messages, including `system`, `user`, and `assistant` messages. | | `messages[].content` | string / array | Yes | Message content. It can be plain text or an array of content blocks containing `text` and `image_url`. | | `temperature` | number | No | Controls randomness. Lower values produce more deterministic results. | | `top_p` | number | No | Controls nucleus sampling. Lower values make output more focused. | | `max_tokens` | number | No | Maximum number of tokens to generate in the response. | | `stream` | boolean | No | Whether to enable streaming output. | | `tools` | array | No | Tool definitions for tool-calling workflows. | | `tool_choice` | string / object | No | Controls whether and how the model uses tools. | | `chat_template_kwargs` | object | No | Extension field for enabling Thinking and other features in OpenAI-compatible requests. | | `thinking` | object | No | Field for enabling Thinking mode in Anthropic-compatible requests. | ## Image URL Input Agnes 2.5 Flash supports passing text and image URLs in the same `messages` request. | Input Type | Format | Description | | - | - | - | | Text | `text` | Plain text instruction or question. | | Image URL | `image_url` | Pass image content through a publicly accessible image URL. | ```json theme={null} { "role": "user", "content": [ { "type": "text", "text": "Describe the content of this image." }, { "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } } ] } ``` ## Request Examples ```bash theme={null} curl https://apihub.agnes-ai.com/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-2.5-flash", "messages": [ { "role": "system", "content": "You are a helpful AI assistant." }, { "role": "user", "content": "Explain how autonomous agents use tools to complete tasks." } ], "temperature": 0.7, "max_tokens": 1024 }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-2.5-flash", "messages": [ { "role": "user", "content": "Write a short product introduction for an AI assistant app." } ], "stream": true }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-2.5-flash", "messages": [ { "role": "user", "content": "What is the weather like in Singapore today?" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Get the current weather for a location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and country" } }, "required": ["location"] } } } ] }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-2.5-flash", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe the content of this image." }, { "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } } ] } ] }' ``` ## Response Format ```json theme={null} { "id": "chatcmpl_xxx", "object": "chat.completion", "created": 1774432125, "model": "agnes-2.5-flash", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Autonomous agents use tools by understanding the user's goal, breaking it into steps, selecting the right tools, executing actions, and using the results to complete the task." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 35, "completion_tokens": 58, "total_tokens": 93 } } ``` ### Response Fields | Field | Type | Description | | - | - | - | | `id` | string | Unique ID of the completion request. | | `object` | string | Object type, usually `chat.completion`. | | `created` | integer | Request timestamp. | | `model` | string | Model used for the request. | | `choices` | array | List of generated responses. | | `choices[].message.role` | string | Role of the message sender. | | `choices[].message.content` | string | Content generated by the model. | | `choices[].finish_reason` | string | Reason generation stopped. | | `usage` | object | Token usage information. | ## Responses API In addition to Chat Completions, this model supports the OpenAI Responses API. Use `input` instead of `messages`. ### Responses endpoint ```text theme={null} POST https://apihub.agnes-ai.com/v1/responses ``` ### Responses request parameters | Parameter | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Model name. Use `agnes-2.5-flash`. | | `input` | string / array | Yes | A plain text prompt or an array of structured input messages. | | `max_output_tokens` | integer | No | Maximum output budget. Use a larger value for reasoning models to avoid an `incomplete` response. | ```bash theme={null} curl https://apihub.agnes-ai.com/v1/responses \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-2.5-flash", "input": "Explain how autonomous agents use tools.", "max_output_tokens": 1024 }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/responses \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-2.5-flash", "input": [ { "role": "user", "content": [ { "type": "input_text", "text": "Explain how autonomous agents use tools." } ] } ], "max_output_tokens": 1024 }' ``` ### Responses output format ```json theme={null} { "id": "resp_xxx", "object": "response", "status": "completed", "model": "agnes-2.5-flash", "output": [ { "type": "reasoning", "summary": [] }, { "type": "message", "role": "assistant", "status": "completed", "content": [ { "type": "output_text", "text": "Autonomous agents use tools to retrieve data and perform actions." } ] } ], "usage": { "input_tokens": 40, "output_tokens": 80, "total_tokens": 120 }, "error": null, "incomplete_details": null } ``` | Field | Type | Description | | - | - | - | | `id` | string | Unique response ID. | | `object` | string | Object type, usually `response`. | | `status` | string | Response state, such as `completed` or `incomplete`. | | `output` | array | Ordered response items, including reasoning and assistant messages. | | `output[].type` | string | Item type, such as `reasoning` or `message`. | | `output[].content[].type` | string | Content type. Generated text uses `output_text`. | | `output[].content[].text` | string | Generated assistant text. | | `usage` | object | Token usage information. | | `error` | object / null | Error details when the request fails. | | `incomplete_details` | object / null | Explains why a response stopped before completion. | The current response does not include a top-level `output_text` convenience field. Extract generated text from message items where `output[].type` is `message` and `output[].content[].type` is `output_text`. Reasoning items are optional and can use either `content[].reasoning_text` or `summary[].summary_text`. Token usage field names can also vary by model: support both `input_tokens` / `output_tokens` and `prompt_tokens` / `completion_tokens`. If `status` is `incomplete`, inspect `incomplete_details` and retry with a larger `max_output_tokens` value. Reasoning models can consume part of the output budget before producing assistant text. ## Messages API This model also supports the Anthropic-compatible Messages API. Send conversation input in `messages` and authenticate with `x-api-key`. ### Messages endpoint ```text theme={null} POST https://apihub.agnes-ai.com/v1/messages ``` ### Messages headers ```bash theme={null} -H "x-api-key: YOUR_API_KEY" -H "anthropic-version: 2023-06-01" -H "Content-Type: application/json" ``` ### Messages request parameters | Parameter | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Model name. Use `agnes-2.5-flash`. | | `max_tokens` | integer | Yes | Maximum number of output tokens. Use a larger value for reasoning models. | | `messages` | array | Yes | Conversation messages containing `user` and `assistant` roles. | | `messages[].role` | string | Yes | Message role. Use `user` or `assistant`. | | `messages[].content` | string / array | Yes | Plain text or an array of Anthropic-compatible content blocks. | | `system` | string / array | No | System instruction for the request. | | `temperature` | number | No | Controls output randomness. | | `stream` | boolean | No | Whether to return a streaming response. | ### Messages request example ```bash theme={null} curl https://apihub.agnes-ai.com/v1/messages \ -H "x-api-key: YOUR_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-2.5-flash", "max_tokens": 1024, "system": "You are a helpful AI assistant.", "messages": [ { "role": "user", "content": "Explain how autonomous agents use tools." } ] }' ``` ### Messages response format ```json theme={null} { "id": "msg_xxx", "type": "message", "role": "assistant", "model": "agnes-2.5-flash", "content": [ { "type": "text", "text": "Autonomous agents use tools to retrieve information and perform actions." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 290, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "output_tokens": 28 } } ``` | Field | Type | Description | | - | - | - | | `id` | string | Unique message ID. | | `type` | string | Object type, usually `message`. | | `role` | string | Response role, usually `assistant`. | | `model` | string | Model used for the request. | | `content` | array | Ordered response content blocks. | | `content[].type` | string | Content block type. Generated text uses `text`. | | `content[].text` | string | Generated assistant text. | | `stop_reason` | string | Reason generation stopped, such as `end_turn` or `max_tokens`. | | `usage.input_tokens` | integer | Number of input tokens used. | | `usage.output_tokens` | integer | Number of output tokens generated. | | `usage.cache_creation_input_tokens` | integer | Input tokens written to the prompt cache. | | `usage.cache_read_input_tokens` | integer | Input tokens read from the prompt cache. | Read generated text from content blocks where `content[].type` is `text`. If `stop_reason` is `max_tokens`, retry with a larger `max_tokens` value. ## Thinking Mode For coding, debugging, reasoning, and agent workflows, you can enable Thinking mode to improve task decomposition and problem-solving quality. ```json theme={null} { "model": "agnes-2.5-flash", "messages": [ { "role": "user", "content": "Help me write a Python script to process a CSV file." } ], "chat_template_kwargs": { "enable_thinking": true } } ``` ```json theme={null} { "model": "agnes-2.5-flash", "messages": [ { "role": "user", "content": "Help me refactor this TypeScript function and explain the changes." } ], "thinking": { "type": "enabled", "budget_tokens": 2048 } } ``` For regular coding tasks, start with `budget_tokens: 2048`. For complex debugging, refactoring, or multi-step agent workflows, increase the budget as needed. ## Best Practices ```text theme={null} [Role] + [Task] + [Context] + [Requirements] + [Output Format] ``` ```text theme={null} You are a product marketing expert. Write a concise App Store description for an AI assistant app. The tone should be clear, professional, and user-friendly. ``` ```text theme={null} Help me debug this React component. The issue is that the button state does not update after clicking. Explain the cause and provide the corrected code. ``` ```text theme={null} You are an autonomous research agent. Search for relevant information, summarize the key findings, and return the result in a structured format with source links. ``` ```text theme={null} Analyze this screenshot. Identify the main UI elements, explain the possible issue, and provide suggestions to improve the user experience. ``` ## Limits and Pricing Agnes 2.5 Flash is generally available. Availability, rate limits, and billing behavior follow the entitlement shown for your Agnes AI account and API key. | Item | Value | | - | - | | Context window | `512K` | | Maximum output | `65.5K` | | Type | Standard Price | Current Price | | - | - | - | | Cached input | `$0.005 / 1M tokens` | `$0 / 1M tokens` | | Input tokens | `$0.05 / 1M tokens` | `$0 / 1M tokens` | | Output tokens | `$0.15 / 1M tokens` | `$0 / 1M tokens` | ## Integration Checklist Use `agnes-2.5-flash` as the model name. Basic chat completion requests must include `model` and `messages`. Image inputs must use publicly accessible `image_url` values. Set `stream` to `true` when you need streaming responses. # Agnes 2.5 Pro Source: https://wiki.agnes-ai.com/en/docs/agnes-25-pro The commercial stable version of the benchmark-listed Agnes 2.5 Pro Beta model for advanced coding, scientific reasoning, long-context analysis, agentic workflows, and multimodal understanding. Agnes 2.5 Pro is the commercial stable version of the benchmark-listed Agnes 2.5 Pro Beta model. It is designed for advanced coding, scientific reasoning, long-context analysis, agentic workflows, and multimodal understanding. The model is available through the OpenAI-compatible Chat Completions API. `agnes-2.5-pro` Chat Completions: `POST /v1/chat/completions`
Responses: `POST /v1/responses`
Messages: `POST /v1/messages` Paid reasoning model with text and image input. Based on the Artificial Analysis listing for Agnes 2.5 Pro Beta. ## Overview Agnes 2.5 Pro is intended for production workloads that need stronger reasoning depth than flash-class models, including complex code tasks, science and math reasoning, long-context understanding, knowledge-intensive Q\&A, and agentic terminal or workflow tasks. It uses the same base integration pattern as other Agnes text models: | Item | Value | | - | - | | Base URL | `https://apihub.agnes-ai.com/v1` | | Endpoint | `POST /v1/chat/completions` | | Model name | `agnes-2.5-pro` | | Input modalities | Text and image URL | | Output modality | Text | | Release date | August 1, 2026 | | Billing | Paid model | The hosted Agnes 2.5 Pro Alpha API is deprecated, while its official weights remain open source under Apache 2.0 on [Hugging Face](https://huggingface.co/Agnes-AI/Agnes-2.5-Pro-Alpha). Agnes 2.5 Pro is the commercial stable API version of the benchmark-listed Beta model. External benchmark metadata may change as Artificial Analysis updates its listing. ## Core Capabilities Suitable for scientific reasoning, knowledge-intensive questions, and multi-step analysis. Designed for code generation, debugging, refactoring, test generation, and agentic coding workflows. Handles long documents, structured context, and multi-turn reasoning tasks. Accepts image URL inputs for visual analysis and multimodal reasoning. Supports OpenAI-compatible function calling and external tool orchestration. Supports streaming responses for interactive product experiences. ## Artificial Analysis Results The following metrics are based on the Artificial Analysis data provided for the benchmark-listed Agnes 2.5 Pro Alpha model. | Summary Item | Value | | - | - | | Intelligence summary rank | `#9 / 153` | | Price summary rank | `#46 / 153` | | Cache hit price summary rank | `#8 / 153` | | Metric | Score | | - | -: | | Intelligence Index | `39` | | GPQA | `87.6%` | | SciCode | `42.2%` | | LCR | `63.7%` | | Omniscience | `-26.3` | | Accuracy | `32.3%` | | Non-hallucination | `13.3%` | | CritPt | `10.9%` | | HLE | `31.9%` | | TerminalBench v2.1 | `67.0%` | | GDPval v2 | `1170 elo` | | Tau3 | `11.6%` | View the benchmark model profile, summary, and pricing analysis. Compare the benchmark-listed Agnes 2.5 Pro Alpha model with other listed models. ## API Reference ### Endpoint ```text theme={null} POST https://apihub.agnes-ai.com/v1/chat/completions ``` ### Headers ```bash theme={null} -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" ``` ### Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Model name. Use `agnes-2.5-pro`. | | `messages` | array | Yes | Conversation messages, including `system`, `user`, and `assistant` messages. | | `messages[].content` | string / array | Yes | Message content. It can be plain text or an array of content blocks containing `text` and `image_url`. | | `temperature` | number | No | Controls randomness. Lower values produce more deterministic output. | | `top_p` | number | No | Controls nucleus sampling. | | `max_tokens` | number | No | Maximum number of tokens to generate in the response. | | `stream` | boolean | No | Whether to enable streaming output. | | `tools` | array | No | Tool definitions for tool-calling workflows. | | `tool_choice` | string / object | No | Controls whether and how the model uses tools. | | `chat_template_kwargs` | object | No | Extension field for OpenAI-compatible requests. | | `thinking` | object | No | Field for enabling Thinking mode in Anthropic-compatible requests. | ## Image URL Input Agnes 2.5 Pro supports text and image URL inputs in the same `messages` request. ```json theme={null} { "role": "user", "content": [ { "type": "text", "text": "Analyze this architecture diagram and identify possible failure points." }, { "type": "image_url", "image_url": { "url": "https://example.com/diagram.png" } } ] } ``` ## Request Examples ```bash theme={null} curl https://apihub.agnes-ai.com/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-2.5-pro", "messages": [ { "role": "system", "content": "You are a precise technical assistant." }, { "role": "user", "content": "Explain the tradeoffs between optimistic locking and pessimistic locking in distributed systems." } ], "temperature": 0.3, "max_tokens": 1200 }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-2.5-pro", "messages": [ { "role": "user", "content": "Review this TypeScript API handler for security issues, explain the risks, and provide a corrected version." } ], "temperature": 0.2, "max_tokens": 2000 }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-2.5-pro", "messages": [ { "role": "user", "content": "Create a step-by-step migration plan for moving a monolith to services." } ], "stream": true }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-2.5-pro", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Summarize this chart and call out any anomalies." }, { "type": "image_url", "image_url": { "url": "https://example.com/chart.png" } } ] } ] }' ``` ## Response Format ```json theme={null} { "id": "chatcmpl_xxx", "object": "chat.completion", "created": 1784899200, "model": "agnes-2.5-pro", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "..." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 120, "completion_tokens": 300, "total_tokens": 420 } } ``` ### Response Fields | Field | Type | Description | | - | - | - | | `id` | string | Unique ID of the completion request. | | `object` | string | Object type, usually `chat.completion`. | | `created` | integer | Request timestamp. | | `model` | string | Model used for the request. | | `choices` | array | List of generated responses. | | `choices[].message.role` | string | Role of the message sender. | | `choices[].message.content` | string | Content generated by the model. | | `choices[].finish_reason` | string | Reason generation stopped. | | `usage` | object | Token usage information. | ## Responses API In addition to Chat Completions, this model supports the OpenAI Responses API. Use `input` instead of `messages`. ### Responses endpoint ```text theme={null} POST https://apihub.agnes-ai.com/v1/responses ``` ### Responses request parameters | Parameter | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Model name. Use `agnes-2.5-pro`. | | `input` | string / array | Yes | A plain text prompt or an array of structured input messages. | | `max_output_tokens` | integer | No | Maximum output budget. Use a larger value for reasoning models to avoid an `incomplete` response. | ```bash theme={null} curl https://apihub.agnes-ai.com/v1/responses \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-2.5-pro", "input": "Explain how autonomous agents use tools.", "max_output_tokens": 1024 }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/responses \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-2.5-pro", "input": [ { "role": "user", "content": [ { "type": "input_text", "text": "Explain how autonomous agents use tools." } ] } ], "max_output_tokens": 1024 }' ``` ### Responses output format ```json theme={null} { "id": "resp_xxx", "object": "response", "status": "completed", "model": "agnes-2.5-pro", "output": [ { "type": "reasoning", "summary": [] }, { "type": "message", "role": "assistant", "status": "completed", "content": [ { "type": "output_text", "text": "Autonomous agents use tools to retrieve data and perform actions." } ] } ], "usage": { "input_tokens": 40, "output_tokens": 80, "total_tokens": 120 }, "error": null, "incomplete_details": null } ``` | Field | Type | Description | | - | - | - | | `id` | string | Unique response ID. | | `object` | string | Object type, usually `response`. | | `status` | string | Response state, such as `completed` or `incomplete`. | | `output` | array | Ordered response items, including reasoning and assistant messages. | | `output[].type` | string | Item type, such as `reasoning` or `message`. | | `output[].content[].type` | string | Content type. Generated text uses `output_text`. | | `output[].content[].text` | string | Generated assistant text. | | `usage` | object | Token usage information. | | `error` | object / null | Error details when the request fails. | | `incomplete_details` | object / null | Explains why a response stopped before completion. | The current response does not include a top-level `output_text` convenience field. Extract generated text from message items where `output[].type` is `message` and `output[].content[].type` is `output_text`. Reasoning items are optional and can use either `content[].reasoning_text` or `summary[].summary_text`. Token usage field names can also vary by model: support both `input_tokens` / `output_tokens` and `prompt_tokens` / `completion_tokens`. If `status` is `incomplete`, inspect `incomplete_details` and retry with a larger `max_output_tokens` value. Reasoning models can consume part of the output budget before producing assistant text. ## Messages API This model also supports the Anthropic-compatible Messages API. Send conversation input in `messages` and authenticate with `x-api-key`. ### Messages endpoint ```text theme={null} POST https://apihub.agnes-ai.com/v1/messages ``` ### Messages headers ```bash theme={null} -H "x-api-key: YOUR_API_KEY" -H "anthropic-version: 2023-06-01" -H "Content-Type: application/json" ``` ### Messages request parameters | Parameter | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Model name. Use `agnes-2.5-pro`. | | `max_tokens` | integer | Yes | Maximum number of output tokens. Use a larger value for reasoning models. | | `messages` | array | Yes | Conversation messages containing `user` and `assistant` roles. | | `messages[].role` | string | Yes | Message role. Use `user` or `assistant`. | | `messages[].content` | string / array | Yes | Plain text or an array of Anthropic-compatible content blocks. | | `system` | string / array | No | System instruction for the request. | | `temperature` | number | No | Controls output randomness. | | `stream` | boolean | No | Whether to return a streaming response. | ### Messages request example ```bash theme={null} curl https://apihub.agnes-ai.com/v1/messages \ -H "x-api-key: YOUR_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-2.5-pro", "max_tokens": 1024, "system": "You are a helpful AI assistant.", "messages": [ { "role": "user", "content": "Explain how autonomous agents use tools." } ] }' ``` ### Messages response format ```json theme={null} { "id": "msg_xxx", "type": "message", "role": "assistant", "model": "agnes-2.5-pro", "content": [ { "type": "text", "text": "Autonomous agents use tools to retrieve information and perform actions." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 290, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "output_tokens": 28 } } ``` | Field | Type | Description | | - | - | - | | `id` | string | Unique message ID. | | `type` | string | Object type, usually `message`. | | `role` | string | Response role, usually `assistant`. | | `model` | string | Model used for the request. | | `content` | array | Ordered response content blocks. | | `content[].type` | string | Content block type. Generated text uses `text`. | | `content[].text` | string | Generated assistant text. | | `stop_reason` | string | Reason generation stopped, such as `end_turn` or `max_tokens`. | | `usage.input_tokens` | integer | Number of input tokens used. | | `usage.output_tokens` | integer | Number of output tokens generated. | | `usage.cache_creation_input_tokens` | integer | Input tokens written to the prompt cache. | | `usage.cache_read_input_tokens` | integer | Input tokens read from the prompt cache. | Read generated text from content blocks where `content[].type` is `text`. If `stop_reason` is `max_tokens`, retry with a larger `max_tokens` value. ## Limits and Pricing Agnes 2.5 Pro is a paid commercial stable model. Usage is billed by cache read, input, and output tokens. | Item | Value | | - | - | | Context window | `1M` tokens | | Max output | `65536` tokens | | Input modalities | Text, image | | Output modalities | Text | | Reasoning | Yes | | Model weights | Proprietary, not open source | | Type | USD Price | | - | -: | | Input cache hit / Cache Read | `$0.045 / M tokens` | | Input cache miss / Input | `$0.45 / M tokens` | | Output | `$0.90 / M tokens` | The cached-input price is 10% of the regular input-token price. Pricing and availability may vary by account, region, billing configuration, or later pricing updates. Use the Agnes AI platform dashboard as the source of truth for your account. ## Best Practices Use Agnes 2.5 Pro for tasks where correctness and multi-step reasoning matter more than raw latency, such as scientific reasoning, complex policy analysis, and long-form technical planning. Provide the target language, framework, existing code, error messages, expected behavior, and constraints. Ask for root-cause analysis before the patch when debugging complex issues. Use structured sections, filenames, or document labels inside the prompt so the model can refer to sources and produce traceable conclusions. ## Integration Checklist Use `agnes-2.5-pro` as the model name. Confirm that your account has access to the paid Agnes 2.5 Pro commercial stable model. Basic chat completion requests must include `model` and `messages`. Use publicly accessible `image_url` values for image inputs. Track cache read, input, and output token usage because this is a paid model. # Agnes 3.0 Flash Source: https://wiki.agnes-ai.com/en/docs/agnes-30-flash A new-generation Agnes AI text model with stronger Agnes Code task execution, tool orchestration, and trustworthy delivery. Agnes 3.0 Flash is Agnes AI's all-new next-generation text model for agentic coding and tool-driven tasks, with a focus on stronger end-to-end execution quality. `agnes-3.0-flash` Chat Completions: `POST /v1/chat/completions`
Responses: `POST /v1/responses`
Messages: `POST /v1/messages` New-generation text model with text and image-URL input. Focused on stable execution, reliable tool use, long-task context retention, and high-quality delivery. Cached input: `$0.005 / 1M tokens`; input: `$0.05 / 1M tokens`; output: `$0.15 / 1M tokens`. All three items are currently `$0`. ## Overview Agnes 3.0 Flash is designed for real-world agent tasks and development workflows, covering the full execution path from task understanding and planning to tool use and final delivery. It focuses on stability, instruction following, grounded execution, and output integrity in complex tasks, helping developers build more reliable agent applications. Use the following API information to integrate the model: | Item | Value | | - | - | | Base URL | `https://apihub.agnes-ai.com/v1` | | Chat Completions | `POST /v1/chat/completions` | | Responses API | `POST /v1/responses` | | Messages API | `POST /v1/messages` | | Model name | `agnes-3.0-flash` | | Input modalities | Text and image URL | | Output modality | Text | | Context window | `512K` | | Maximum output | `65,536 tokens` | ## Core directions Better suited to Agnes Code and coding-agent workflows, strengthening execution from requirements understanding through final delivery. Stronger function calling, tool selection, and multi-step tool orchestration for more stable agent execution. Maintains objectives, constraints, and runtime context throughout long-running and multi-turn tasks. Strengthens factual grounding, result verification, and output integrity while reducing unsupported conclusions and incorrect completion claims. ## Capability highlights Improved task planning, execution, and result verification help complex agent tasks reach genuine completion with stronger delivery quality. The model interprets tool definitions, selects appropriate tools, and coordinates multi-step calls more reliably, reducing ineffective calls, repetition, and abnormal loops. Long-running and multi-turn tasks stay aligned with the original objective, constraints, and runtime context, reducing task drift and missed requirements. Greater attention to tool results and factual grounding reduces unsupported conclusions and incorrect completion claims, making execution status more transparent and dependable. Reduced repetition, malformed text, and unnecessary exposure of internal reasoning produce clearer, more coherent responses that are ready for delivery. ## Chat Completions API ### Endpoint and headers ```text theme={null} POST https://apihub.agnes-ai.com/v1/chat/completions ``` ```bash theme={null} -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" ``` ### Request fields Agnes 3.0 Flash supports the following request fields. | Field | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Use `agnes-3.0-flash`. | | `messages` | array | Yes | Conversation messages with `system`, `user`, and `assistant` roles. | | `messages[].content` | string / array | Yes | Plain text or content blocks containing `text` and `image_url`. | | `temperature` | number | No | Controls output randomness. | | `top_p` | number | No | Controls nucleus sampling. | | `max_tokens` | integer | No | Maximum number of output tokens. | | `stream` | boolean | No | Returns a streamed response when `true`. | | `tools` | array | No | Tool definitions for function-calling workflows. | | `tool_choice` | string / object | No | Controls whether and how the model calls tools. | | `chat_template_kwargs` | object | No | Extension field for Thinking and other compatible features. | ## Image URL input Pass public image URLs together with text in `messages[].content`. ```json theme={null} { "role": "user", "content": [ { "type": "text", "text": "Describe the key information in this image." }, { "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } } ] } ``` ### Basic request ```bash theme={null} curl https://apihub.agnes-ai.com/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-3.0-flash", "messages": [ { "role": "user", "content": "Explain how an agent should choose and call a tool." } ], "max_tokens": 1024 }' ``` ### Response format Chat Completions responses use an OpenAI-compatible structure: ```json theme={null} { "id": "chatcmpl_xxx", "object": "chat.completion", "model": "agnes-3.0-flash", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "An agent should select a tool based on the task and the tool's declared capability." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 24, "completion_tokens": 18, "total_tokens": 42 } } ``` ### Tool-calling request ```json theme={null} { "model": "agnes-3.0-flash", "messages": [ { "role": "user", "content": "What is the weather in Shanghai?" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Get the current weather for a city.", "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] } } } ] } ``` Read generated text from `choices[].message.content`. For a tool call, inspect `choices[].message.tool_calls`, execute the requested function in your application, append its result to `messages`, and submit the next Chat Completions request. ## Responses API The Responses API accepts text or structured messages through `input`. ```text theme={null} POST https://apihub.agnes-ai.com/v1/responses ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/responses \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-3.0-flash", "input": "Summarize this task and list the tools you would need.", "max_output_tokens": 1024 }' ``` | Field | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Use `agnes-3.0-flash`. | | `input` | string / array | Yes | Plain-text prompt or structured input messages. | | `max_output_tokens` | integer | No | Maximum output budget. | Read generated text from a message item in `output` where `output[].type` is `message` and `output[].content[].type` is `output_text`. The response object may also contain `usage`, `error`, and `incomplete_details`. ## Messages API Agnes 3.0 Flash supports the Anthropic-compatible Messages API. ```text theme={null} POST https://apihub.agnes-ai.com/v1/messages ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/messages \ -H "x-api-key: YOUR_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-3.0-flash", "max_tokens": 1024, "messages": [ { "role": "user", "content": "Draft a concise product announcement and list the next actions." } ] }' ``` | Field | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Use `agnes-3.0-flash`. | | `max_tokens` | integer | Yes | Maximum output-token budget. | | `messages` | array | Yes | Messages with `user` and `assistant` roles. | | `messages[].content` | string / array | Yes | Plain text or Anthropic-compatible content blocks. | | `system` | string / array | No | System instruction. | | `temperature` | number | No | Controls output randomness. | | `stream` | boolean | No | Returns a streamed response when `true`. | Read generated text from `content[]` items where `content[].type` is `text`. ## Thinking mode Enable Thinking mode when your integration needs more deliberate task decomposition or reasoning. ```json theme={null} { "model": "agnes-3.0-flash", "messages": [ { "role": "user", "content": "Plan the implementation steps for this repository task." } ], "chat_template_kwargs": { "enable_thinking": true } } ``` ```json theme={null} { "model": "agnes-3.0-flash", "max_tokens": 2048, "messages": [ { "role": "user", "content": "Plan the implementation steps for this repository task." } ], "thinking": { "type": "enabled", "budget_tokens": 2048 } } ``` ## Best practices State the task objective, repository or runtime context, constraints, expected output, and tool permissions. Return tool results to the conversation before asking the model for the next action. Write narrow tool descriptions and JSON schemas. Validate tool arguments in your application before executing side-effecting actions. Break complex work into verifiable stages, and preserve the objective, constraints, and key tool results across each execution round. Model availability, rate limits, and billing are determined by your Agnes AI account and API key. ## Limits and pricing Availability and rate limits follow the entitlement shown for your Agnes AI account and API key. | Item | Value | | - | - | | Context window | `512K` | | Maximum output | `65,536 tokens` | | Billing item | List price | Current price | | - | -: | -: | | Cached input | `$0.005 / 1M tokens` | `$0 / 1M tokens` | | Input tokens | `$0.05 / 1M tokens` | `$0 / 1M tokens` | | Output tokens | `$0.15 / 1M tokens` | `$0 / 1M tokens` | # Agnes 3.0 Flash Max Source: https://wiki.agnes-ai.com/en/docs/agnes-30-flash-max API integration, request and response examples, and USD pricing for the paid Agnes 3.0 Flash Max text model. Agnes 3.0 Flash Max is a paid Agnes AI text model available on the international site. Use `agnes-3.0-flash-max` as the model name. Regular input, cached input, and output tokens are billed separately. ## Overview Use the following endpoints to integrate Agnes 3.0 Flash Max into chat, coding, and tool-calling applications. | Item | Value | | - | - | | Model | `agnes-3.0-flash-max` | | Base URL | `https://apihub.agnes-ai.com/v1` | | Endpoints | `POST /v1/chat/completions`, `POST /v1/responses`, `POST /v1/messages` | | Billing | Paid, based on token usage | | Availability | International site | ## Chat Completions API ### Endpoint and headers ```text theme={null} POST https://apihub.agnes-ai.com/v1/chat/completions ``` ```bash theme={null} -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" ``` ### Request fields Agnes 3.0 Flash Max supports the following request fields. | Field | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Use `agnes-3.0-flash-max`. | | `messages` | array | Yes | Conversation messages with `system`, `user`, and `assistant` roles. | | `messages[].content` | string / array | Yes | Plain text or content blocks containing `text` and `image_url`. | | `temperature` | number | No | Controls output randomness. | | `top_p` | number | No | Controls nucleus sampling. | | `max_tokens` | integer | No | Maximum number of output tokens. | | `stream` | boolean | No | Returns a streamed response when `true`. | | `tools` | array | No | Tool definitions for function-calling workflows. | | `tool_choice` | string / object | No | Controls whether and how the model calls tools. | | `chat_template_kwargs` | object | No | Extension field for Thinking and other compatible features. | ## Image URL input Pass public image URLs together with text in `messages[].content`. ```json theme={null} { "role": "user", "content": [ { "type": "text", "text": "Describe the key information in this image." }, { "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } } ] } ``` ### Basic request ```bash theme={null} curl https://apihub.agnes-ai.com/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-3.0-flash-max", "messages": [ { "role": "user", "content": "Explain how an agent should choose and call a tool." } ], "max_tokens": 1024 }' ``` ### Response format Chat Completions responses use an OpenAI-compatible structure: ```json theme={null} { "id": "chatcmpl_xxx", "object": "chat.completion", "model": "agnes-3.0-flash-max", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "An agent should select a tool based on the task and the tool's declared capability." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 24, "completion_tokens": 18, "total_tokens": 42 } } ``` ### Tool-calling request ```json theme={null} { "model": "agnes-3.0-flash-max", "messages": [ { "role": "user", "content": "What is the weather in Shanghai?" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Get the current weather for a city.", "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] } } } ] } ``` Read generated text from `choices[].message.content`. For a tool call, inspect `choices[].message.tool_calls`, execute the requested function in your application, append its result to `messages`, and submit the next Chat Completions request. ## Responses API The Responses API accepts text or structured messages through `input`. ```text theme={null} POST https://apihub.agnes-ai.com/v1/responses ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/responses \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-3.0-flash-max", "input": "Summarize this task and list the tools you would need.", "max_output_tokens": 1024 }' ``` | Field | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Use `agnes-3.0-flash-max`. | | `input` | string / array | Yes | Plain-text prompt or structured input messages. | | `max_output_tokens` | integer | No | Maximum output budget. | Read generated text from a message item in `output` where `output[].type` is `message` and `output[].content[].type` is `output_text`. The response object may also contain `usage`, `error`, and `incomplete_details`. ## Messages API Agnes 3.0 Flash Max supports the Anthropic-compatible Messages API. ```text theme={null} POST https://apihub.agnes-ai.com/v1/messages ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/messages \ -H "x-api-key: YOUR_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-3.0-flash-max", "max_tokens": 1024, "messages": [ { "role": "user", "content": "Draft a concise product announcement and list the next actions." } ] }' ``` | Field | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Use `agnes-3.0-flash-max`. | | `max_tokens` | integer | Yes | Maximum output-token budget. | | `messages` | array | Yes | Messages with `user` and `assistant` roles. | | `messages[].content` | string / array | Yes | Plain text or Anthropic-compatible content blocks. | | `system` | string / array | No | System instruction. | | `temperature` | number | No | Controls output randomness. | | `stream` | boolean | No | Returns a streamed response when `true`. | Read generated text from `content[]` items where `content[].type` is `text`. ## Thinking mode Enable Thinking mode when your integration needs more deliberate task decomposition or reasoning. ```json theme={null} { "model": "agnes-3.0-flash-max", "messages": [ { "role": "user", "content": "Plan the implementation steps for this repository task." } ], "chat_template_kwargs": { "enable_thinking": true } } ``` ```json theme={null} { "model": "agnes-3.0-flash-max", "max_tokens": 2048, "messages": [ { "role": "user", "content": "Plan the implementation steps for this repository task." } ], "thinking": { "type": "enabled", "budget_tokens": 2048 } } ``` ## Best practices State the task objective, repository or runtime context, constraints, expected output, and tool permissions. Return tool results to the conversation before asking the model for the next action. Write narrow tool descriptions and JSON schemas. Validate tool arguments in your application before executing side-effecting actions. Break complex work into verifiable stages, and preserve the objective, constraints, and key tool results across each execution round. Model availability, rate limits, and billing are determined by your Agnes AI account and API key. ## Pricing and billing Prices below are in USD for the international site. `M` means one million tokens. This is a paid model; the Agnes 3.0 Flash free offer does not apply. | Billing item | Price | | - | -: | | Prefill input | `$0.08 / M tokens` | | Cached input | `$0.008 / M tokens` | | Output | `$0.40 / M tokens` | Cached-input pricing applies only to input tokens confirmed as cache hits by the service. Other input tokens use the regular input price; the same input token is not billed twice. Availability and rate limits depend on account entitlements. # Agnes 3.0 Pro Source: https://wiki.agnes-ai.com/en/docs/agnes-30-pro A new-generation Pro model, coming soon, for agentic work, professional document analysis, scientific coding, and long-context reasoning. Agnes 3.0 Pro is coming soon. This documentation is available for integration preparation; API availability will be announced at launch. Responses below are format examples, not evidence of current availability. ## Overview Agnes 3.0 Pro is Agnes AI's new-generation Pro model, focused on real-world agentic tasks, professional document understanding, scientific coding, and long-context analysis. It is designed for applications that combine evidence, tools, and reasoning to address complex work. | Item | Value | | - | - | | Model | `agnes-3.0-pro` | | Status | Coming soon | | Base URL | `https://apihub.agnes-ai.com/v1` | | Endpoints | `POST /v1/chat/completions`, `POST /v1/responses`, `POST /v1/messages` | | Input | Text and image URLs | | Output | Text | | Billing | Cache read, regular input, and output tokens | ## Core directions and highlights * **Agentic work**: Focused on analyzing and executing multi-step tasks. * **Professional document analysis**: Designed for extracting evidence and forming conclusions from documents. * **Scientific coding and complex reasoning**: Suitable for scientific computing, code analysis, and technical problem-solving. * **Long-context synthesis**: Supports analysis across long documents and multiple sources. * **Developer workflows**: Includes tool-calling parameters, streaming, and text and image input examples for interactive assistants and agentic applications. ## API Reference ### Endpoint ```text theme={null} POST https://apihub.agnes-ai.com/v1/chat/completions ``` ### Headers ```bash theme={null} -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" ``` ### Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Model name. Use `agnes-3.0-pro`. | | `messages` | array | Yes | Conversation messages, including `system`, `user`, and `assistant` messages. | | `messages[].content` | string / array | Yes | Message content. It can be plain text or an array of content blocks containing `text` and `image_url`. | | `temperature` | number | No | Controls randomness. Lower values produce more deterministic output. | | `top_p` | number | No | Controls nucleus sampling. | | `max_tokens` | number | No | Maximum number of tokens to generate in the response. | | `stream` | boolean | No | Whether to enable streaming output. | | `tools` | array | No | Tool definitions for tool-calling workflows. | | `tool_choice` | string / object | No | Controls whether and how the model uses tools. | | `chat_template_kwargs` | object | No | Extension field for OpenAI-compatible requests. | | `thinking` | object | No | Field for enabling Thinking mode in Anthropic-compatible requests. | ## Image URL Input Agnes 3.0 Pro supports text and image URL inputs in the same `messages` request. ```json theme={null} { "role": "user", "content": [ { "type": "text", "text": "Analyze this architecture diagram and identify possible failure points." }, { "type": "image_url", "image_url": { "url": "https://example.com/diagram.png" } } ] } ``` ## Request Examples ```bash theme={null} curl https://apihub.agnes-ai.com/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-3.0-pro", "messages": [ { "role": "system", "content": "You are a precise technical assistant." }, { "role": "user", "content": "Explain the tradeoffs between optimistic locking and pessimistic locking in distributed systems." } ], "temperature": 0.3, "max_tokens": 1200 }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-3.0-pro", "messages": [ { "role": "user", "content": "Review this TypeScript API handler for security issues, explain the risks, and provide a corrected version." } ], "temperature": 0.2, "max_tokens": 2000 }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-3.0-pro", "messages": [ { "role": "user", "content": "Create a step-by-step migration plan for moving a monolith to services." } ], "stream": true }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-3.0-pro", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Summarize this chart and call out any anomalies." }, { "type": "image_url", "image_url": { "url": "https://example.com/chart.png" } } ] } ] }' ``` ## Response Format ```json theme={null} { "id": "chatcmpl_xxx", "object": "chat.completion", "created": 1784899200, "model": "agnes-3.0-pro", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "..." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 120, "completion_tokens": 300, "total_tokens": 420 } } ``` ### Response Fields | Field | Type | Description | | - | - | - | | `id` | string | Unique ID of the completion request. | | `object` | string | Object type, usually `chat.completion`. | | `created` | integer | Request timestamp. | | `model` | string | Model used for the request. | | `choices` | array | List of generated responses. | | `choices[].message.role` | string | Role of the message sender. | | `choices[].message.content` | string | Content generated by the model. | | `choices[].finish_reason` | string | Reason generation stopped. | | `usage` | object | Token usage information. | ## Responses API In addition to Chat Completions, this model supports the OpenAI Responses API. Use `input` instead of `messages`. ### Responses endpoint ```text theme={null} POST https://apihub.agnes-ai.com/v1/responses ``` ### Responses request parameters | Parameter | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Model name. Use `agnes-3.0-pro`. | | `input` | string / array | Yes | A plain text prompt or an array of structured input messages. | | `max_output_tokens` | integer | No | Maximum output budget. Use a larger value for reasoning models to avoid an `incomplete` response. | ```bash theme={null} curl https://apihub.agnes-ai.com/v1/responses \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-3.0-pro", "input": "Explain how autonomous agents use tools.", "max_output_tokens": 1024 }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/responses \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-3.0-pro", "input": [ { "role": "user", "content": [ { "type": "input_text", "text": "Explain how autonomous agents use tools." } ] } ], "max_output_tokens": 1024 }' ``` ### Responses output format ```json theme={null} { "id": "resp_xxx", "object": "response", "status": "completed", "model": "agnes-3.0-pro", "output": [ { "type": "reasoning", "summary": [] }, { "type": "message", "role": "assistant", "status": "completed", "content": [ { "type": "output_text", "text": "Autonomous agents use tools to retrieve data and perform actions." } ] } ], "usage": { "input_tokens": 40, "output_tokens": 80, "total_tokens": 120 }, "error": null, "incomplete_details": null } ``` | Field | Type | Description | | - | - | - | | `id` | string | Unique response ID. | | `object` | string | Object type, usually `response`. | | `status` | string | Response state, such as `completed` or `incomplete`. | | `output` | array | Ordered response items, including reasoning and assistant messages. | | `output[].type` | string | Item type, such as `reasoning` or `message`. | | `output[].content[].type` | string | Content type. Generated text uses `output_text`. | | `output[].content[].text` | string | Generated assistant text. | | `usage` | object | Token usage information. | | `error` | object / null | Error details when the request fails. | | `incomplete_details` | object / null | Explains why a response stopped before completion. | The current response does not include a top-level `output_text` convenience field. Extract generated text from message items where `output[].type` is `message` and `output[].content[].type` is `output_text`. Reasoning items are optional and can use either `content[].reasoning_text` or `summary[].summary_text`. Token usage field names can also vary by model: support both `input_tokens` / `output_tokens` and `prompt_tokens` / `completion_tokens`. If `status` is `incomplete`, inspect `incomplete_details` and retry with a larger `max_output_tokens` value. Reasoning models can consume part of the output budget before producing assistant text. ## Messages API This model also supports the Anthropic-compatible Messages API. Send conversation input in `messages` and authenticate with `x-api-key`. ### Messages endpoint ```text theme={null} POST https://apihub.agnes-ai.com/v1/messages ``` ### Messages headers ```bash theme={null} -H "x-api-key: YOUR_API_KEY" -H "anthropic-version: 2023-06-01" -H "Content-Type: application/json" ``` ### Messages request parameters | Parameter | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Model name. Use `agnes-3.0-pro`. | | `max_tokens` | integer | Yes | Maximum number of output tokens. Use a larger value for reasoning models. | | `messages` | array | Yes | Conversation messages containing `user` and `assistant` roles. | | `messages[].role` | string | Yes | Message role. Use `user` or `assistant`. | | `messages[].content` | string / array | Yes | Plain text or an array of Anthropic-compatible content blocks. | | `system` | string / array | No | System instruction for the request. | | `temperature` | number | No | Controls output randomness. | | `stream` | boolean | No | Whether to return a streaming response. | ### Messages request example ```bash theme={null} curl https://apihub.agnes-ai.com/v1/messages \ -H "x-api-key: YOUR_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-3.0-pro", "max_tokens": 1024, "system": "You are a helpful AI assistant.", "messages": [ { "role": "user", "content": "Explain how autonomous agents use tools." } ] }' ``` ### Messages response format ```json theme={null} { "id": "msg_xxx", "type": "message", "role": "assistant", "model": "agnes-3.0-pro", "content": [ { "type": "text", "text": "Autonomous agents use tools to retrieve information and perform actions." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 290, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "output_tokens": 28 } } ``` | Field | Type | Description | | - | - | - | | `id` | string | Unique message ID. | | `type` | string | Object type, usually `message`. | | `role` | string | Response role, usually `assistant`. | | `model` | string | Model used for the request. | | `content` | array | Ordered response content blocks. | | `content[].type` | string | Content block type. Generated text uses `text`. | | `content[].text` | string | Generated assistant text. | | `stop_reason` | string | Reason generation stopped, such as `end_turn` or `max_tokens`. | | `usage.input_tokens` | integer | Number of input tokens used. | | `usage.output_tokens` | integer | Number of output tokens generated. | | `usage.cache_creation_input_tokens` | integer | Input tokens written to the prompt cache. | | `usage.cache_read_input_tokens` | integer | Input tokens read from the prompt cache. | Read generated text from content blocks where `content[].type` is `text`. If `stop_reason` is `max_tokens`, retry with a larger `max_tokens` value. ## Limits and Pricing Agnes 3.0 Pro is an upcoming paid model. Usage is billed by cache read, input, and output tokens. | Item | Value | | - | - | | Input modalities | Text, image | | Output modalities | Text | | Reasoning | Yes | | Type | USD Price | | - | -: | | Input cache hit / Cache Read | `$0.045 / M tokens` | | Input cache miss / Input | `$0.45 / M tokens` | | Output | `$0.90 / M tokens` | The cached-input price is 10% of the regular input-token price. Pricing and availability may vary by account, region, billing configuration, or later pricing updates. Use the Agnes AI platform dashboard as the source of truth for your account. ## Best Practices Use Agnes 3.0 Pro for tasks where correctness and multi-step reasoning matter more than raw latency, such as scientific reasoning, complex policy analysis, and long-form technical planning. Provide the target language, framework, existing code, error messages, expected behavior, and constraints. Ask for root-cause analysis before the patch when debugging complex issues. Use structured sections, filenames, or document labels inside the prompt so the model can refer to sources and produce traceable conclusions. ## Integration Checklist Use `agnes-3.0-pro` as the model name. After launch, confirm that your account has access to Agnes 3.0 Pro. Basic chat completion requests must include `model` and `messages`. Use publicly accessible `image_url` values for image inputs. Track cache read, input, and output token usage because this is a paid model. # Agnes Image 2.0 Flash Source: https://wiki.agnes-ai.com/en/docs/agnes-image-20-flash A high-performance image generation and editing model for text-to-image, image-to-image, and multi-image composition workflows. Agnes Image 2.0 Flash is a high-performance Agnes AI image generation and editing model. It supports text-to-image, image-to-image, and multi-image composition workflows for creative design, marketing visuals, e-commerce product images, and social content production. `agnes-image-2.0-flash` `POST /v1/images/generations` Text-to-image, image-to-image, and multi-image composition. All supported output-resolution tiers and input reference images are currently free. ## Overview Agnes Image 2.0 Flash is optimized for fast, high-quality, and cost-effective image production workflows. The model has appeared on the Artificial Analysis image editing leaderboard with an **ELO score of 1,184**, ranking in the **Top 20** range and demonstrating strong image editing capability. ## Core Capabilities Generate images from text prompts. Edit, transform, or enhance existing images. Use multiple reference images to create a new image. Modify composition, style, objects, backgrounds, and scenes. Control artistic style, lighting, layout, and visual direction. Designed for frequent, fast, production-grade creative workflows. ## Use Cases Posters, concept art, and social media visuals. Product ads, campaign creatives, and banners. Object replacement, background replacement, style transfer, and local edits. Combine multiple characters or reference images into one scene. Product image enhancement, product staging, and marketing hero images. Memes, avatars, thumbnails, and lifestyle visual assets. ## API Reference ### Endpoint ```text theme={null} POST https://apihub.agnes-ai.com/v1/images/generations ``` ### Headers ```bash theme={null} -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" ``` ### Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Model name. Use `agnes-image-2.0-flash`. | | `prompt` | string | Yes | Text prompt describing the target image or editing instruction. | | `size` | string | Yes | Output image size, such as `1024x768`, `1024x1024`, or `768x1024`. | | `image` | string\[] | Required for image-to-image | Input image array. Supports public URLs or Data URI Base64. | | `return_base64` | boolean | No | Use this when text-to-image output should be returned as Base64. | | `extra_body.response_format` | string | No | Output format. Common values are `url` and `b64_json`. | ## Important Notes Do not place `response_format` at the top level of the request body. For URL or Base64 output, place it inside `extra_body`. Only `model`, `prompt`, and `size` are required. Do not pass `image`. Pass image URLs or Data URI Base64 values through `extra_body.image`. Image-to-image requests do not require `tags: ["img2img"]`. Use `YOUR_API_KEY` in public documentation. Do not expose real API keys. ## Request Examples ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.0-flash", "prompt": "A clean product photo of a glass cube on a white studio background, soft shadows, high detail", "size": "1024x768", "extra_body": { "response_format": "url" } }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.0-flash", "prompt": "A clean product photo of a glass cube on a white studio background, soft shadows, high detail", "size": "1024x768", "return_base64": true }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.0-flash", "prompt": "Transform this image into a cinematic cyberpunk style while preserving the main subject and composition", "size": "1024x768", "extra_body": { "image": [ "https://example.com/input-image.png" ], "response_format": "url" } }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.0-flash", "prompt": "Make the object orange while preserving the original composition", "size": "1024x768", "extra_body": { "image": [ "https://example.com/input.png" ], "response_format": "b64_json" } }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.0-flash", "prompt": "Combine the two characters into an intense fantasy battle scene, dynamic lighting, detailed background, cinematic composition", "size": "1024x768", "extra_body": { "image": [ "https://example.com/character-1.png", "https://example.com/character-2.png" ], "response_format": "url" } }' ``` ## Response Format ```json theme={null} { "created": 1780000000, "data": [ { "url": "https://storage.googleapis.com/agnes-aigc/xxx.png", "b64_json": null, "revised_prompt": null } ] } ``` ```json theme={null} { "created": 1780000000, "data": [ { "url": null, "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...", "revised_prompt": null } ] } ``` ### Response Fields | Field | Type | Description | | - | - | - | | `created` | integer | Request creation timestamp. | | `data` | array | List of generated image results. | | `data[].url` | string / null | Generated image URL. Usually `null` when using Base64 output. | | `data[].b64_json` | string / null | Base64 image data. Usually `null` when using URL output. | | `data[].revised_prompt` | string / null | Revised prompt if available. Otherwise `null`. | ## Best Practices Provide clear visual instructions, including subject, scene, style, lighting, composition, and quality requirements. ```text theme={null} [Subject] + [Scene / Background] + [Style] + [Lighting] + [Composition] + [Quality Requirements] ``` ```text theme={null} A professional product photo of a wireless headphone on a clean white background, soft studio lighting, sharp details, commercial photography style ``` Clearly describe what should change and what should remain unchanged. ```text theme={null} [Editing Instruction] + [Elements to Preserve] + [Target Style / Scene] + [Lighting] + [Composition] + [Quality Requirements] ``` ```text theme={null} Change the background to a futuristic city at night while keeping the person's face, outfit, and pose unchanged ``` Describe the relationship between the input images and how they should be combined. ```text theme={null} Place the person from the first image beside the robot from the second image in a cinematic sci-fi battle scene ``` ## FAQ Yes. Text-to-image requests only require `model`, `prompt`, and `size`. The `image` parameter is not needed. Yes. Image-to-image requests require input images in `extra_body.image`. No. Do not pass `tags: ["img2img"]`. Use `model`, `prompt`, `size`, and `extra_body.image` instead. In this API structure, `response_format` should be placed inside `extra_body`. Placing it at the top level may cause a `400` error. Use a publicly accessible HTTPS image URL. If the image cannot be made public, use Data URI Base64 input. Image generation may take several seconds to tens of seconds. A client timeout of `60s - 360s` is recommended. ## Pricing `agnes-image-2.0-flash` and `agnes-image-2.1-flash` use the same prices. | Billing item | List price | Current price | | - | -: | -: | | 1K output image | `$10 / 1,000 images` (`$0.010 / image`) | **`$0`** | | 2K output image | `$18 / 1,000 images` (`$0.018 / image`) | **`$0`** | | 3K output image | `$21 / 1,000 images` (`$0.021 / image`) | **`$0`** | | 4K output image | `$24 / 1,000 images` (`$0.024 / image`) | **`$0`** | | Input reference images from the 4th onward | `$0.003 / image` | **`$0 / image`** | At list price, the first 3 input reference images do not incur an additional charge. Currently, all output-resolution tiers and input reference images are free. See [Model Pricing](/en/docs/pricing#image-models) for the complete billing rule. ## Integration Checklist Use `agnes-image-2.0-flash` as the model name. Use `https://apihub.agnes-ai.com/v1/images/generations` as the API endpoint. For text-to-image, include `model`, `prompt`, and `size`. For image-to-image, provide input images through `extra_body.image`. Do not place `response_format` at the top level of the request body. # Agnes Image 2.1 Flash Source: https://wiki.agnes-ai.com/en/docs/agnes-image-21-flash An upgraded image generation model optimized for high-information-density visuals, with support for text-to-image, image-to-image, and multi-image composition workflows. Agnes Image 2.1 Flash is an upgraded Agnes AI image generation model. It supports text-to-image, image-to-image, and multi-image composition workflows. Compared with version 2.0, it is better suited for high-information-density images, complex compositions, and detail-rich visual scenes. `agnes-image-2.1-flash` `POST /v1/images/generations` High-information-density images, complex visual details, and semantic alignment. All supported output-resolution tiers and input reference images are currently free. ## Overview Agnes Image 2.1 Flash can generate images from text prompts and transform, redraw, or stylize input images. Results can be returned as image URLs or Base64 data. Better suited for complex scenes, rich compositions, and multi-layer visual elements. Preserves the original composition and subject layout as much as possible during image-to-image editing. ## Core Capabilities Generate high-quality images from natural language prompts. Transform or improve existing images based on prompt instructions. Use multiple reference images to create a new combined image. Optimized for detail-rich images with complex layouts and dense visual elements. Preserve the original composition and subject layout when editing input images. Use resolution tiers such as `1K`, `2K`, `3K`, or `4K` with a supported aspect ratio. Return generated images as URLs or Base64 data. ## Use Cases Concept art, visual exploration, and poster drafts. Campaign images, product visuals, and social media creatives. Detailed scenes, complex environments, and rich compositions. Style transfer, scene relighting, and background transformation. Product photos, mockups, and commercial visuals. Covers, banners, thumbnails, and post images. ## API Reference ### Endpoint ```text theme={null} POST https://apihub.agnes-ai.com/v1/images/generations ``` ### Headers ```bash theme={null} -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" ``` ### Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Model name. Use `agnes-image-2.1-flash`. | | `prompt` | string | Yes | Text instruction for image generation or image editing. | | `size` | string | Yes | Output size tier. Recommended values are `1K`, `2K`, `3K`, and `4K`. Legacy exact-size values such as `1024x768` are also accepted, but unsupported sizes may be normalized. | | `ratio` | string | No | Aspect ratio used with tier-based `size`. Supported values include `1:1`, `3:4`, `4:3`, `16:9`, `9:16`, `2:3`, `3:2`, and `21:9`. Default is `1:1`. | | `image` | string\[] | Required for image-to-image or multi-image composition | Input image array. Supports public image URLs or Data URI Base64. Pass multiple images for multi-image composition. | | `return_base64` | boolean | No | Use this when text-to-image output should be returned as Base64. | | `extra_body` | object | No | Additional parameters for advanced workflows. | | `extra_body.response_format` | string | No | Output format. Common values are `url` and `b64_json`. | ## Size and Ratio For predictable output dimensions, use `size` together with `ratio`. * Recommended `size` values: `1K`, `2K`, `3K`, `4K` * Supported `ratio` values: `1:1`, `3:4`, `4:3`, `16:9`, `9:16`, `2:3`, `3:2`, `21:9` * If you request an unsupported exact size such as `1920x1080` or `2560x1440`, the service may map it to the nearest supported tier and aspect ratio. * For common 16:9 display assets such as `1920x1080` or `2560x1440`, request `size: "2K"` with `ratio: "16:9"` and then crop or resize downstream if you need an exact final canvas. `1920x1080` and `2560x1440` are standard display resolutions, but they are not the native output dimensions for this image model. When exact sizes are not supported, the response size may be normalized, for example to the 16:9 `1K` output size `1312x736`. ### Output Dimension Reference | Ratio | 1K | 2K | 3K | 4K | | - | - | - | - | - | | `1:1` | `1024x1024` | `2048x2048` | `3072x3072` | `4096x4096` | | `3:4` | `864x1152` | `1728x2304` | `2592x3456` | `3456x4608` | | `4:3` | `1152x864` | `2304x1728` | `3456x2592` | `4608x3456` | | `16:9` | `1312x736` | `2624x1472` | `3936x2208` | `5248x2944` | | `9:16` | `736x1312` | `1472x2624` | `2208x3936` | `2944x5248` | | `2:3` | `832x1248` | `1664x2496` | `2496x3744` | `3328x4992` | | `3:2` | `1248x832` | `2496x1664` | `3744x2496` | `4992x3328` | | `21:9` | `1568x672` | `3136x1344` | `4704x2016` | `6272x2688` | ### Example: 16:9 2K Output ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.1-flash", "prompt": "A cinematic product hero image for a desktop monitor wallpaper, clean lighting, high detail", "size": "2K", "ratio": "16:9", "extra_body": { "response_format": "url" } }' ``` This returns the 16:9 `2K` tier output size, `2624x1472`. ## Important Notes Do not place `response_format` at the top level of the request body. For URL output, use `extra_body.response_format: "url"`. For image-to-image Base64 output, use `extra_body.response_format: "b64_json"`. Required parameters are `model`, `prompt`, and `size`. Use tier-based `size` values such as `2K` with `ratio`, for example `16:9`. Provide input image URLs or Data URI Base64 values in `extra_body.image`. Pass multiple reference images in `extra_body.image`. For text-to-image, use top-level `return_base64: true`. Image-to-image requests do not require `tags: ["img2img"]`. ## Request Examples ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.1-flash", "prompt": "A luminous floating city above a misty canyon at sunrise, cinematic realism", "size": "1024x768", "extra_body": { "response_format": "url" } }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.1-flash", "prompt": "A clean product photo of a glass cube on a white studio background, soft shadows, high detail", "size": "1024x768", "return_base64": true }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.1-flash", "prompt": "Transform the scene into a rain-soaked cyberpunk night with neon reflections while preserving the original composition", "size": "1024x768", "extra_body": { "image": [ "https://example.com/input-image.png" ], "response_format": "url" } }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.1-flash", "prompt": "Make the object orange while preserving the original composition", "size": "1024x768", "extra_body": { "image": [ "https://example.com/input-image.png" ], "response_format": "b64_json" } }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.1-flash", "prompt": "Combine the two characters into an intense fantasy battle scene, dynamic lighting, detailed background, cinematic composition", "size": "1024x768", "extra_body": { "image": [ "https://example.com/character-1.png", "https://example.com/character-2.png" ], "response_format": "url" } }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.1-flash", "prompt": "Make the object matte black while preserving the original composition", "size": "1024x768", "extra_body": { "image": [ "data:image/png;base64,BASE64_HERE" ], "response_format": "b64_json" } }' ``` ## Response Format ```json theme={null} { "created": 1780000000, "data": [ { "url": "https://storage.googleapis.com/agnes-aigc/xxx.png", "b64_json": null, "revised_prompt": null } ] } ``` Generated image URL path: ```text theme={null} data[0].url ``` ```json theme={null} { "created": 1780000000, "data": [ { "url": null, "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...", "revised_prompt": null } ] } ``` Generated Base64 image path: ```text theme={null} data[0].b64_json ``` ### Response Fields | Field | Type | Description | | - | - | - | | `created` | integer | Request creation timestamp. | | `data` | array | List of generated image results. | | `data[].url` | string / null | Generated image URL. Usually `null` when using Base64 output. | | `data[].b64_json` | string / null | Base64 image data. Usually `null` when using URL output. | | `data[].revised_prompt` | string / null | Revised prompt if available. Otherwise `null`. | ## Prompting Guide For better image generation results, use a clear prompt structure that describes the subject, environment, style, lighting, composition, and quality requirements. ```text theme={null} [Subject] + [Scene / Environment] + [Style] + [Lighting] + [Composition] + [Quality Requirements] ``` ```text theme={null} A luminous floating city above a misty canyon at sunrise, cinematic realism, wide-angle composition, rich architectural details, soft golden light, high visual density ``` Clearly describe what should change and what should remain unchanged. ```text theme={null} [Change Request] + [New Style / Scene] + [Elements to Add or Remove] + [Elements to Preserve] ``` ```text theme={null} Turn the daytime street scene into a cinematic cyberpunk night scene, add neon signs and wet road reflections, while preserving the original street layout, camera angle, and main building shapes. ``` Describe the role of each reference image and how they should be combined in the final result. ```text theme={null} [Reference roles] + [Target scene] + [Relationship between images] + [Style / Lighting / Composition] ``` ```text theme={null} Use the first image as the main character and the second image as the product reference. Create a cinematic campaign poster that preserves the character identity and product shape, with natural lighting and a clean commercial composition. ``` Agnes Image 2.1 Flash is optimized for complex and detail-rich visuals. For best results, describe the visual hierarchy clearly. Recommended elements: * Main subject * Background environment * Important secondary details * Style and lighting * Composition constraints * Elements to preserve for image-to-image tasks ```text theme={null} A large fantasy harbor city built on cliffs, hundreds of small boats, layered stone bridges, glowing windows, distant mountains, cloudy sunset sky, cinematic fantasy realism, wide-angle composition, rich architectural details, high visual density ``` ## Common Errors and Troubleshooting Do not place `response_format` at the top level. Incorrect: ```json theme={null} { "model": "agnes-image-2.1-flash", "prompt": "A futuristic city", "size": "1024x768", "response_format": "url" } ``` Correct: ```json theme={null} { "model": "agnes-image-2.1-flash", "prompt": "A futuristic city", "size": "1024x768", "extra_body": { "response_format": "url" } } ``` Do not pass `tags: ["img2img"]`. Image-to-image only requires an input image array. ```json theme={null} { "model": "agnes-image-2.1-flash", "prompt": "Make the object blue while preserving the original composition", "size": "1024x768", "extra_body": { "image": ["https://example.com/input.png"], "response_format": "url" } } ``` Use public HTTPS image URLs that do not require login, cookies, or private request headers. If the image cannot be made public, use Data URI Base64 input. Image generation may take several seconds to tens of seconds depending on prompt complexity, image size, and server load. A client timeout of `60s - 360s` is recommended. Image-to-image and multi-image composition require an input image array in `extra_body.image`. ## Pricing `agnes-image-2.0-flash` and `agnes-image-2.1-flash` use the same prices. | Billing item | List price | Current price | | - | -: | -: | | 1K output image | `$10 / 1,000 images` (`$0.010 / image`) | **`$0`** | | 2K output image | `$18 / 1,000 images` (`$0.018 / image`) | **`$0`** | | 3K output image | `$21 / 1,000 images` (`$0.021 / image`) | **`$0`** | | 4K output image | `$24 / 1,000 images` (`$0.024 / image`) | **`$0`** | | Input reference images from the 4th onward | `$0.003 / image` | **`$0 / image`** | At list price, the first 3 input reference images do not incur an additional charge. Currently, all output-resolution tiers and input reference images are free. See [Model Pricing](/en/docs/pricing#image-models) for the complete billing rule. ## Integration Checklist Use `agnes-image-2.1-flash` as the model name. Use `https://apihub.agnes-ai.com/v1/images/generations` as the API endpoint. For text-to-image, include `model`, `prompt`, and `size`. For predictable dimensions, use `size` tiers such as `1K` or `2K` together with `ratio`. For image-to-image and multi-image composition, provide input images through `extra_body.image`. Do not expose temporary or real API keys in public documentation. # Agnes Image 2.5 Flash Source: https://wiki.agnes-ai.com/en/docs/agnes-image-25-flash The latest-generation Agnes image model, with capabilities that comprehensively exceed Agnes Image 2.1 Flash and support for text-to-image, image-to-image, and multi-image composition. Agnes Image 2.5 Flash is the latest generation of the Agnes AI image model. Its overall image generation, editing, composition, detail rendering, and prompt-alignment capabilities comprehensively exceed Agnes Image 2.1 Flash. Its request and response parameters, supported sizes, pricing, and billing method remain identical to Agnes Image 2.1 Flash. `agnes-image-2.5-flash` `POST /v1/images/generations` High-information-density images, complex visual details, and semantic alignment. All supported output-resolution tiers and input reference images are currently free. ## Overview Agnes Image 2.5 Flash can generate images from text prompts and transform, redraw, or stylize input images. It preserves the complete integration contract of Agnes Image 2.1 Flash while providing stronger generation quality across supported workflows. Results can be returned as image URLs or Base64 data. Better suited for complex scenes, rich compositions, and multi-layer visual elements. Preserves the original composition and subject layout as much as possible during image-to-image editing. ## Core Capabilities Generate high-quality images from natural language prompts. Transform or improve existing images based on prompt instructions. Use multiple reference images to create a new combined image. Optimized for detail-rich images with complex layouts and dense visual elements. Preserve the original composition and subject layout when editing input images. Use resolution tiers such as `1K`, `2K`, `3K`, or `4K` with a supported aspect ratio. Return generated images as URLs or Base64 data. ## Use Cases Concept art, visual exploration, and poster drafts. Campaign images, product visuals, and social media creatives. Detailed scenes, complex environments, and rich compositions. Style transfer, scene relighting, and background transformation. Product photos, mockups, and commercial visuals. Covers, banners, thumbnails, and post images. ## API Reference ### Endpoint ```text theme={null} POST https://apihub.agnes-ai.com/v1/images/generations ``` ### Headers ```bash theme={null} -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" ``` ### Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Model name. Use `agnes-image-2.5-flash`. | | `prompt` | string | Yes | Text instruction for image generation or image editing. | | `size` | string | Yes | Output size tier. Recommended values are `1K`, `2K`, `3K`, and `4K`. Legacy exact-size values such as `1024x768` are also accepted, but unsupported sizes may be normalized. | | `ratio` | string | No | Aspect ratio used with tier-based `size`. Supported values include `1:1`, `3:4`, `4:3`, `16:9`, `9:16`, `2:3`, `3:2`, and `21:9`. Default is `1:1`. | | `image` | string\[] | Required for image-to-image or multi-image composition | Input image array. Supports public image URLs or Data URI Base64. Pass multiple images for multi-image composition. | | `return_base64` | boolean | No | Use this when text-to-image output should be returned as Base64. | | `extra_body` | object | No | Additional parameters for advanced workflows. | | `extra_body.response_format` | string | No | Output format. Common values are `url` and `b64_json`. | ## Size and Ratio For predictable output dimensions, use `size` together with `ratio`. * Recommended `size` values: `1K`, `2K`, `3K`, `4K` * Supported `ratio` values: `1:1`, `3:4`, `4:3`, `16:9`, `9:16`, `2:3`, `3:2`, `21:9` * If you request an unsupported exact size such as `1920x1080` or `2560x1440`, the service may map it to the nearest supported tier and aspect ratio. * For common 16:9 display assets such as `1920x1080` or `2560x1440`, request `size: "2K"` with `ratio: "16:9"` and then crop or resize downstream if you need an exact final canvas. `1920x1080` and `2560x1440` are standard display resolutions, but they are not the native output dimensions for this image model. When exact sizes are not supported, the response size may be normalized, for example to the 16:9 `1K` output size `1312x736`. ### Output Dimension Reference | Ratio | 1K | 2K | 3K | 4K | | - | - | - | - | - | | `1:1` | `1024x1024` | `2048x2048` | `3072x3072` | `4096x4096` | | `3:4` | `864x1152` | `1728x2304` | `2592x3456` | `3456x4608` | | `4:3` | `1152x864` | `2304x1728` | `3456x2592` | `4608x3456` | | `16:9` | `1312x736` | `2624x1472` | `3936x2208` | `5248x2944` | | `9:16` | `736x1312` | `1472x2624` | `2208x3936` | `2944x5248` | | `2:3` | `832x1248` | `1664x2496` | `2496x3744` | `3328x4992` | | `3:2` | `1248x832` | `2496x1664` | `3744x2496` | `4992x3328` | | `21:9` | `1568x672` | `3136x1344` | `4704x2016` | `6272x2688` | ### Example: 16:9 2K Output ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.5-flash", "prompt": "A cinematic product hero image for a desktop monitor wallpaper, clean lighting, high detail", "size": "2K", "ratio": "16:9", "extra_body": { "response_format": "url" } }' ``` This returns the 16:9 `2K` tier output size, `2624x1472`. ## Important Notes Do not place `response_format` at the top level of the request body. For URL output, use `extra_body.response_format: "url"`. For image-to-image Base64 output, use `extra_body.response_format: "b64_json"`. Required parameters are `model`, `prompt`, and `size`. Use tier-based `size` values such as `2K` with `ratio`, for example `16:9`. Provide input image URLs or Data URI Base64 values in `extra_body.image`. Pass multiple reference images in `extra_body.image`. For text-to-image, use top-level `return_base64: true`. Image-to-image requests do not require `tags: ["img2img"]`. ## Request Examples ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.5-flash", "prompt": "A luminous floating city above a misty canyon at sunrise, cinematic realism", "size": "1024x768", "extra_body": { "response_format": "url" } }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.5-flash", "prompt": "A clean product photo of a glass cube on a white studio background, soft shadows, high detail", "size": "1024x768", "return_base64": true }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.5-flash", "prompt": "Transform the scene into a rain-soaked cyberpunk night with neon reflections while preserving the original composition", "size": "1024x768", "extra_body": { "image": [ "https://example.com/input-image.png" ], "response_format": "url" } }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.5-flash", "prompt": "Make the object orange while preserving the original composition", "size": "1024x768", "extra_body": { "image": [ "https://example.com/input-image.png" ], "response_format": "b64_json" } }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.5-flash", "prompt": "Combine the two characters into an intense fantasy battle scene, dynamic lighting, detailed background, cinematic composition", "size": "1024x768", "extra_body": { "image": [ "https://example.com/character-1.png", "https://example.com/character-2.png" ], "response_format": "url" } }' ``` ```bash theme={null} curl https://apihub.agnes-ai.com/v1/images/generations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-image-2.5-flash", "prompt": "Make the object matte black while preserving the original composition", "size": "1024x768", "extra_body": { "image": [ "data:image/png;base64,BASE64_HERE" ], "response_format": "b64_json" } }' ``` ## Response Format ```json theme={null} { "created": 1780000000, "data": [ { "url": "https://storage.googleapis.com/agnes-aigc/xxx.png", "b64_json": null, "revised_prompt": null } ] } ``` Generated image URL path: ```text theme={null} data[0].url ``` ```json theme={null} { "created": 1780000000, "data": [ { "url": null, "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...", "revised_prompt": null } ] } ``` Generated Base64 image path: ```text theme={null} data[0].b64_json ``` ### Response Fields | Field | Type | Description | | - | - | - | | `created` | integer | Request creation timestamp. | | `data` | array | List of generated image results. | | `data[].url` | string / null | Generated image URL. Usually `null` when using Base64 output. | | `data[].b64_json` | string / null | Base64 image data. Usually `null` when using URL output. | | `data[].revised_prompt` | string / null | Revised prompt if available. Otherwise `null`. | ## Prompting Guide For better image generation results, use a clear prompt structure that describes the subject, environment, style, lighting, composition, and quality requirements. ```text theme={null} [Subject] + [Scene / Environment] + [Style] + [Lighting] + [Composition] + [Quality Requirements] ``` ```text theme={null} A luminous floating city above a misty canyon at sunrise, cinematic realism, wide-angle composition, rich architectural details, soft golden light, high visual density ``` Clearly describe what should change and what should remain unchanged. ```text theme={null} [Change Request] + [New Style / Scene] + [Elements to Add or Remove] + [Elements to Preserve] ``` ```text theme={null} Turn the daytime street scene into a cinematic cyberpunk night scene, add neon signs and wet road reflections, while preserving the original street layout, camera angle, and main building shapes. ``` Describe the role of each reference image and how they should be combined in the final result. ```text theme={null} [Reference roles] + [Target scene] + [Relationship between images] + [Style / Lighting / Composition] ``` ```text theme={null} Use the first image as the main character and the second image as the product reference. Create a cinematic campaign poster that preserves the character identity and product shape, with natural lighting and a clean commercial composition. ``` Agnes Image 2.5 Flash is optimized for complex and detail-rich visuals. For best results, describe the visual hierarchy clearly. Recommended elements: * Main subject * Background environment * Important secondary details * Style and lighting * Composition constraints * Elements to preserve for image-to-image tasks ```text theme={null} A large fantasy harbor city built on cliffs, hundreds of small boats, layered stone bridges, glowing windows, distant mountains, cloudy sunset sky, cinematic fantasy realism, wide-angle composition, rich architectural details, high visual density ``` ## Common Errors and Troubleshooting Do not place `response_format` at the top level. Incorrect: ```json theme={null} { "model": "agnes-image-2.5-flash", "prompt": "A futuristic city", "size": "1024x768", "response_format": "url" } ``` Correct: ```json theme={null} { "model": "agnes-image-2.5-flash", "prompt": "A futuristic city", "size": "1024x768", "extra_body": { "response_format": "url" } } ``` Do not pass `tags: ["img2img"]`. Image-to-image only requires an input image array. ```json theme={null} { "model": "agnes-image-2.5-flash", "prompt": "Make the object blue while preserving the original composition", "size": "1024x768", "extra_body": { "image": ["https://example.com/input.png"], "response_format": "url" } } ``` Use public HTTPS image URLs that do not require login, cookies, or private request headers. If the image cannot be made public, use Data URI Base64 input. Image generation may take several seconds to tens of seconds depending on prompt complexity, image size, and server load. A client timeout of `60s - 360s` is recommended. Image-to-image and multi-image composition require an input image array in `extra_body.image`. ## Pricing `agnes-image-2.1-flash` and `agnes-image-2.5-flash` use the same prices and billing method. | Billing item | List price | Current price | | - | -: | -: | | 1K output image | `$10 / 1,000 images` (`$0.010 / image`) | **`$0`** | | 2K output image | `$18 / 1,000 images` (`$0.018 / image`) | **`$0`** | | 3K output image | `$21 / 1,000 images` (`$0.021 / image`) | **`$0`** | | 4K output image | `$24 / 1,000 images` (`$0.024 / image`) | **`$0`** | | Input reference images from the 4th onward | `$0.003 / image` | **`$0 / image`** | At list price, the first 3 input reference images do not incur an additional charge. Currently, all output-resolution tiers and input reference images are free. See [Model Pricing](/en/docs/pricing#image-models) for the complete billing rule. ## Integration Checklist Use `agnes-image-2.5-flash` as the model name. Use `https://apihub.agnes-ai.com/v1/images/generations` as the API endpoint. For text-to-image, include `model`, `prompt`, and `size`. For predictable dimensions, use `size` tiers such as `1K` or `2K` together with `ratio`. For image-to-image and multi-image composition, provide input images through `extra_body.image`. Do not expose temporary or real API keys in public documentation. # Agnes Video 2.5 Source: https://wiki.agnes-ai.com/en/docs/agnes-video-25 Integrate Agnes Video 2.5 through an OpenAI Videos-compatible API for text-to-video, keyframe control, and multimodal reference generation. Agnes Video 2.5 is now available on the international site and uses an asynchronous video generation API. First call `POST /v1/videos` to create a task, then use the returned `video_id` with `GET /agnesapi?video_id=&model_name=agnes-video-2.5` to retrieve progress and results. See “Billing” below for prices and billing rules. `agnes-video-2.5` `POST /v1/videos` `GET /agnesapi?video_id=&model_name=agnes-video-2.5` 720P: `$0.025 / second`; 1080P and 1K: `$0.040 / second`; 2K: `$0.055 / second`. ## Core Capabilities Generate videos with subject motion, scene dynamics, and camera movement from a text prompt. Constrain the composition and transition with a first frame, a last frame, or both. Use images, audio, and videos as content, style, rhythm, or motion references. Continue or reinterpret motion, visual appearance, and timing from a reference video. Use audio or a video soundtrack as a reference to improve rhythm and audio-visual consistency. Generate landscape, portrait, square, and ultrawide video outputs. ## Quickstart ### 1. Get an API Key Create an API key in the Agnes AI platform. Store and use the key only on your server. Never expose it in frontend code or a public repository. ### 2. Set the Base URL International Base URL: ```text theme={null} https://apihub.agnes-ai.com/v1 ``` The examples below use environment variables: ```bash theme={null} export AGNES_API_KEY="YOUR_API_KEY" export AGNES_BASE_URL="https://apihub.agnes-ai.com/v1" ``` ### 3. Create a Video Task ```bash theme={null} curl -sS -X POST "$AGNES_BASE_URL/videos" \ -H "Authorization: Bearer $AGNES_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "agnes-video-2.5", "prompt": "A futuristic city street after rain, neon lights reflected on the pavement, a silver sports car passing slowly, cinematic camera movement, natural ambient sound", "seconds": "5", "mode": "text", "size": "720P", "aspect_ratio": "16:9" }' ``` Save `video_id` from the create response. `id` and `task_id` identify the asynchronous task, while `video_id` is used to retrieve progress and results. ### 4. Retrieve the Result ```bash theme={null} curl -sS "https://apihub.agnes-ai.com/agnesapi?video_id=VIDEO_ID&model_name=agnes-video-2.5" \ -H "Authorization: Bearer $AGNES_API_KEY" ``` Use the query form with `model_name` for every mode. Poll every `1–2` seconds until `status` becomes `completed` or `failed`. When the task is complete, use `url` to play or download the video. ## API Reference ### Create a Video Task ```text theme={null} POST https://apihub.agnes-ai.com/v1/videos ``` Headers: ```http theme={null} Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` ### Common Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Model ID. Use `agnes-video-2.5`. | | `prompt` | string | Yes | Video description. In reference mode, use ``, `