/v1/async/sonarCreate Async Chat CompletionSubmit an asynchronous chat completion request.
Request body
requiredapplication/json
AsyncApiChatCompletionsRequest
Request body for creating an asynchronous chat completion
idempotency_keyvalueUnique key to prevent duplicate requests
Show child attributes
anyOf · 2 options
requestobjectrequiredShow child attributes
disable_searchvalueWhen true, disables all web search capabilities. The model responds based solely on its training data
Show child attributes
anyOf · 2 options
enable_search_classifiervalueWhen true, uses a classifier to determine if web search is needed for the query
Show child attributes
anyOf · 2 options
image_domain_filtervalueLimit image results to specific domains
Show child attributes
anyOf · 2 options
image_format_filtervalueFilter image results by format (e.g. png, jpg)
Show child attributes
anyOf · 2 options
language_preferencevalueISO 639-1 language code for preferred response language
Show child attributes
anyOf · 2 options
last_updated_after_filtervalueReturn results last updated after this date (MM/DD/YYYY)
Show child attributes
anyOf · 2 options
last_updated_before_filtervalueReturn results last updated before this date (MM/DD/YYYY)
Show child attributes
anyOf · 2 options
max_tokensvalueMaximum number of completion tokens to generate
Show child attributes
anyOf · 2 options
messagesarray of objectrequiredArray of messages forming the conversation history
Show child attributes
Show array items
contentvaluerequiredShow child attributes
anyOf · 3 options
Structured Content
Show array items
anyOf · 5 options
ChatMessageContentTextChunk
textstringrequiredtypestringrequiredChatMessageContentImageChunk
image_urlvaluerequiredShow child attributes
anyOf · 2 options
URL
urlstringrequiredtypestringrequiredChatMessageContentFileChunk
file_namevalueShow child attributes
anyOf · 2 options
file_urlvaluerequiredShow child attributes
anyOf · 2 options
typestringrequiredChatMessageContentPDFChunk
pdf_urlvaluerequiredShow child attributes
anyOf · 2 options
typestringrequiredChatMessageContentVideoChunk
typestringrequiredvideo_urlvaluerequiredShow child attributes
anyOf · 2 options
VideoURL
frame_intervalvalueShow child attributes
anyOf · 2 options
urlstringrequiredrolestringrequiredChat roles enum
modelstringrequiredModel to use, for example, sonar-pro
reasoning_effortvalueControls how much effort the model spends on reasoning
Show child attributes
anyOf · 2 options
response_formatvalueOptional. Controls the output format. Omit for default text output. Set `type` to `json_schema` for structured output.
Show child attributes
anyOf · 3 options
ResponseFormatText
typestringrequiredMust be `text`.
ResponseFormatJSONSchema
Constrains the model output to match the provided JSON schema.
json_schemaobjectrequiredShow child attributes
descriptionvalueShow child attributes
anyOf · 2 options
namevalueShow child attributes
anyOf · 2 options
schemaobjectrequiredstrictvalueShow child attributes
anyOf · 2 options
typestringrequiredMust be `json_schema`.
return_imagesvalueWhen true, include image results in the response
Show child attributes
anyOf · 2 options
return_related_questionsvalueWhen true, generates suggested follow-up queries based on the search results
Show child attributes
anyOf · 2 options
search_after_date_filtervalueReturn results published after this date (MM/DD/YYYY)
Show child attributes
anyOf · 2 options
search_before_date_filtervalueReturn results published before this date (MM/DD/YYYY)
Show child attributes
anyOf · 2 options
search_domain_filtervalueLimit search results to specific domains (e.g. github.com, wikipedia.org)
Show child attributes
anyOf · 2 options
search_language_filtervalueFilter results by language using ISO 639-1 codes (e.g. en, fr, de)
Show child attributes
anyOf · 2 options
search_modevalueSource of search results (web, academic, or sec)
Show child attributes
anyOf · 2 options
search_recency_filtervalueFilter by publication recency (hour, day, week, month, or year)
Show child attributes
anyOf · 2 options
stopvalueStop sequences. Generation stops when one of these strings is produced
Show child attributes
anyOf · 3 options
streamvalueIf true, returns streaming SSE response
Show child attributes
anyOf · 2 options
stream_modestringControls the format of streaming events. 'full' suppresses reasoning events and includes metadata inline; 'concise' emits reasoning events separately
temperaturevalueControls randomness in the response. Higher values make output more random. Range: 0-2
Show child attributes
anyOf · 2 options
top_pvalueNucleus sampling parameter. Controls diversity via nucleus sampling
Show child attributes
anyOf · 2 options
web_search_optionsobjectConfiguration options for web search behavior
Show child attributes
image_results_enhanced_relevancebooleanWhen true, applies enhanced relevance filtering to image results
search_context_sizestringAmount of search context to include (low, medium, or high)
search_typevalueSearch type (fast for speed, pro for quality, auto to let the model decide)
Show child attributes
anyOf · 2 options
user_locationvalueShow child attributes
anyOf · 2 options
UserLocation
User's geographic location for search personalization
cityvalueCity name
Show child attributes
anyOf · 2 options
countryvalueISO 3166-1 alpha-2 country code
Show child attributes
anyOf · 2 options
latitudevalueLatitude coordinate
Show child attributes
anyOf · 2 options
longitudevalueLongitude coordinate
Show child attributes
anyOf · 2 options
regionvalueState or region name
Show child attributes
anyOf · 2 options
{
"request": {
"messages": [
{
"content": "<string>",
"role": "<string>"
}
],
"model": "sonar-deep-research"
}
}Responses
AsyncApiChatCompletionsResponse
completed_atvalueUnix timestamp when processing completed
Show child attributes
anyOf · 2 options
created_atintegerrequiredUnix timestamp when the request was created
error_messagevalueError message if the request failed
Show child attributes
anyOf · 2 options
failed_atvalueUnix timestamp when the request failed (if applicable)
Show child attributes
anyOf · 2 options
idstringrequiredUnique identifier for the async request
modelstringrequiredModel used for the request
responsevalueShow child attributes
anyOf · 2 options
CompletionResponse
choicesarray of objectrequiredArray of completion choices
Show child attributes
Show array items
A single completion choice
deltaobjectrequiredShow child attributes
contentvaluerequiredShow child attributes
anyOf · 3 options
Structured Content
Show array items
anyOf · 5 options
rolestringrequiredChat roles enum
finish_reasonvalueReason generation stopped (stop or length)
Show child attributes
anyOf · 2 options
indexintegerrequiredIndex of the choice in the array
citationsvalueURLs of sources used to generate the response
Show child attributes
anyOf · 2 options
createdintegerrequiredUnix timestamp when the completion was created
idstringrequiredUnique identifier for the completion
imagesvalueArray of images returned when return_images is true
Show child attributes
anyOf · 2 options
Show array items
heightintegerrequiredHeight of the image in pixels
image_urlstringrequiredURL of the image
origin_urlstringrequiredOriginal URL where the image was found
titlestringrequiredTitle or description of the image
widthintegerrequiredWidth of the image in pixels
modelstringrequiredModel used for generation
objectstringObject type identifier
related_questionsvalueArray of related questions returned when return_related_questions is true
Show child attributes
anyOf · 2 options
search_resultsvalueSearch results used for context in the response
Show child attributes
anyOf · 2 options
Show array items
A single search result from the web
datevaluePublication date of the result
Show child attributes
anyOf · 2 options
last_updatedvalueDate the result was last updated
Show child attributes
anyOf · 2 options
snippetstringText snippet from the search result
sourcestringSource type of the result (web or attachment)
titlestringrequiredTitle of the search result page
urlstringrequiredURL of the search result page
usagevalueShow child attributes
anyOf · 2 options
UsageInfo
Token usage and cost information for a request
citation_tokensvalueNumber of tokens used for citations
Show child attributes
anyOf · 2 options
completion_tokensintegerrequiredNumber of tokens in the completion/output
costobjectrequiredCost breakdown for a chat completion request
Show child attributes
citation_tokens_costvalueCost for citation tokens in USD
Show child attributes
anyOf · 2 options
input_tokens_costnumberrequiredCost for input tokens in USD
output_tokens_costnumberrequiredCost for output tokens in USD
reasoning_tokens_costvalueCost for reasoning tokens in USD
Show child attributes
anyOf · 2 options
request_costvalueCost for web search requests in USD (includes pro search cost if applicable)
Show child attributes
anyOf · 2 options
search_queries_costvalueCost for search queries in USD
Show child attributes
anyOf · 2 options
total_costnumberrequiredTotal cost for the request in USD
num_search_queriesvalueNumber of search queries executed
Show child attributes
anyOf · 2 options
prompt_tokensintegerrequiredNumber of tokens in the prompt/input
reasoning_tokensvalueNumber of tokens used for reasoning
Show child attributes
anyOf · 2 options
search_context_sizevalueSize of search context used
Show child attributes
anyOf · 2 options
total_tokensintegerrequiredTotal tokens used (prompt + completion)
started_atvalueUnix timestamp when processing started
Show child attributes
anyOf · 2 options
statusstringrequiredStatus enum for async processing.
{
"completed_at": 0,
"created_at": 0,
"error_message": null,
"failed_at": 0,
"id": "string",
"model": "string",
"response": {
"choices": [
{
"delta": {
"content": [
{
"file_name": null,
"file_url": {},
"type": "file_url"
}
],
"role": "assistant"
},
"finish_reason": "length",
"index": 0,
"message": {
"content": [
{
"file_name": null,
"file_url": {},
"type": "file_url"
}
],
"role": "assistant"
}
}
],
"citations": [
"string"
],
"created": 0,
"id": "string",
"images": [
{
"height": 0,
"image_url": "string",
"origin_url": "string",
"title": "string",
"width": 0
}
],
"model": "string",
"object": "chat.completion",
"related_questions": [
"string"
],
"search_results": [
{
"date": null,
"last_updated": null,
"snippet": "",
"source": "web",
"title": "string",
"url": "string"
}
],
"usage": {
"citation_tokens": 0,
"completion_tokens": 0,
"cost": {
"citation_tokens_cost": null,
"input_tokens_cost": 0,
"output_tokens_cost": 0,
"reasoning_tokens_cost": null,
"request_cost": null,
"search_queries_cost": null,
"total_cost": 0
},
"num_search_queries": 0,
"prompt_tokens": 0,
"reasoning_tokens": 0,
"search_context_size": null,
"total_tokens": 0
}
},
"started_at": 0,
"status": "COMPLETED"
}HTTPValidationError
detailarray of objectShow child attributes
Show array items
locarray of valuerequiredShow child attributes
Show array items
anyOf · 2 options
msgstringrequiredtypestringrequired{
"detail": [
{
"loc": [
0
],
"msg": "string",
"type": "string"
}
]
}