Create Cached Content

POST https://api.tikway.ai/v1beta/cachedContents

Create Cached Content

cURL

curl --request POST \
  --url https://api.tikway.ai/v1beta/cachedContents \
  --header 'Content-Type: application/json' \
  --header 'x-goog-api-key: <api-key>' \
  --data '
{
  "model": "models/gemini-2.5-flash",
  "displayName": "unicorn-story-context",
  "systemInstruction": {
    "parts": [
      {
        "text": "You are a creative bedtime-story assistant. Keep stories gentle and suitable for children."
      }
    ]
  },
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Reference material: Unicorns are magical horses with a single horn. They live in enchanted forests and help kind-hearted people."
        }
      ]
    }
  ],
  "ttl": "3600s"
}
'

200

{
  "name": "cachedContents/abc123xyz",
  "displayName": "starry-night-reference",
  "model": "models/gemini-2.5-flash",
  "createTime": "2026-09-10T08:30:00.123456Z",
  "updateTime": "2026-09-10T08:30:00.123456Z",
  "expireTime": "2026-09-10T09:30:00.123456Z",
  "usageMetadata": {
    "totalTokenCount": 1864
  }
}

Authorizations

x-goog-api-key · string · header · required

Tikway API Key. Passed through the x-goog-api-key request header according to the Gemini native protocol.

Body

application/json

Create a request body for cached content. The cached content is preprocessed and can be reused in subsequent build requests. The cache can only be used for the model specified when it was created.

model · string · required

The name of the model resource used to create and use this cache. The cache can only be used for the models specified here, in the format models/{model}. This field is required and cannot be modified after creation.

Pattern: ^models/[^/]+$

Examples:

"models/gemini-1.5-flash-001"

"models/gemini-2.5-flash"

contents · object[]

A list of content that needs to be cached. It can contain a single round of content, or it can contain multiple historical rounds of content in dialogue order. This field is for input only and cannot be modified after the cache is created.

Minimum array length: 1

Hide child attributes

contents. parts · object[] · required

A list of parts that make up the current content. Each Part can represent text, inline files, uploaded files, function calls, function responses, or code execution information.

Minimum array length: 1

Hide child attributes

contents.parts. text · string

Plain text content.

contents.parts. inlineData · object

To embed binary data directly in the request, the data needs to be Base64 encoded.

Hide child attributes

contents.parts.inlineData. mimeType · string · required

MIME type for inline data, such as text/plain, image/jpeg, application/pdf.

contents.parts.inlineData. data · string<byte> · required

Base64 encoded file contents.

contents.parts.inlineData. displayName · string

The display name of the inline media.

contents.parts. fileData · object

File reference obtained after uploading via Gemini File API.

Hide child attributes

contents.parts.fileData. mimeType · string · required

The MIME type of the referenced file, such as text/plain, image/jpeg, application/pdf.

contents.parts.fileData. fileUri · string · required

File URI returned by the File API.

contents.parts.fileData. displayName · string

The display name of the file.

contents.parts. functionCall · object

Function call information generated by the model in historical conversations.

Hide child attributes

contents.parts.functionCall. name · string · required

The name of the function to be called should be consistent with the function name declared in tools.functionDeclarations.

contents.parts.functionCall. args · object · required

The parameters used when calling the function, the structure is determined by the parameters JSON Schema of the corresponding function.

contents.parts. functionResponse · object

The result returned to the model after the client executes the function.

Hide child attributes

contents.parts.functionResponse. name · string · required

The name of the executed function should be consistent with the corresponding functionCall.name.

contents.parts.functionResponse. response · object · required

Function execution result. Can contain data, status, or error information returned by the function.

contents.parts. executableCode · object

Code generated by the model that can be run by the code execution environment.

Hide child attributes

contents.parts.executableCode. language · enum<string> · required

The programming language used by the code. LANGUAGE_UNSPECIFIED means unspecified, PYTHON means Python.

Available options: LANGUAGE_UNSPECIFIED, PYTHON

contents.parts.executableCode. code · string · required

The source code needs to be executed.

contents.parts.executableCode. id · string

Executable code block ID.

contents.parts. codeExecutionResult · object

The execution results returned by the code execution environment.

Hide child attributes

contents.parts.codeExecutionResult. outcome · enum<string> · required

Code execution status. OUTCOME_OK indicates success, OUTCOME_FAILED indicates failure, and OUTCOME_DEADLINE_EXCEEDED indicates execution timeout.

Available options: OUTCOME_UNSPECIFIED, OUTCOME_OK, OUTCOME_FAILED, OUTCOME_DEADLINE_EXCEEDED

contents.parts.codeExecutionResult. output · string

Standard output, error messages, or other textual results produced by code execution.

contents.parts.codeExecutionResult. id · string

The corresponding code block ID.

contents.parts. thought · boolean

Indicates whether the current Part belongs to the thinking content of the model. Usually generated by the server, the original value should be maintained when returning historical content.

contents.parts. thoughtSignature · string<byte>

A signature of what the model thinks about. The historical content of the model should be kept intact when returned and should not be modified or generated by the client.

contents.parts. partMetadata · object

Custom metadata associated with the content block.

contents.parts. mediaResolution · object

The resolution of this media content block.

Hide child attributes

contents.parts.mediaResolution. level · enum<string>

Available options: MEDIA_RESOLUTION_UNSPECIFIED, MEDIA_RESOLUTION_LOW, MEDIA_RESOLUTION_MEDIUM, MEDIA_RESOLUTION_HIGH

contents.parts. mediaProcessing · string

How video content is processed.

contents.parts. audioTranscription · object

Audio transcription information.

contents.parts. speechMetadata · object

Speech synthesis related metadata.

contents.parts. toolCall · object

Server-side tool calls that need to be returned by the client.

contents.parts. toolResponse · object

The execution result of the server tool call.

contents.parts. videoMetadata · object

Video content metadata.

contents. role · enum<string>

The role the content belongs to. user represents user content, and model represents historical content generated by the model.

Available options: user, model

tools · object[]

A list of tools that the model can use when subsequently generating content. This field is for input only and cannot be modified after the cache is created.

Hide child attributes

tools. functionDeclarations · object[]

A list of function declarations provided by the client for use by the model.

Minimum array length: 1

Hide child attributes

tools.functionDeclarations. name · string · required

function name. The name should be unique and comply with the naming rules supported by the server.

tools.functionDeclarations. description · string · required

Function usage and calling scenario description, the model will determine whether to call the function based on this description.

tools.functionDeclarations. parameters · object

JSON Schema of function parameters. Usually the type of the root node is object, and the parameters are declared through properties.

tools.functionDeclarations. response · object

JSON Schema of the function return value, used to describe the structure of the function execution result.

tools.functionDeclarations. behavior · enum<string>

How the function call is executed.

Available options: UNSPECIFIED, BLOCKING, NON_BLOCKING

tools.functionDeclarations. parametersJsonSchema · any

JSON Schema of function parameters; mutually exclusive with parameters .

tools.functionDeclarations. responseJsonSchema · any

JSON Schema of the function response; mutually exclusive with response .

tools. codeExecution · object

Enable model code execution capabilities. The current configuration object is usually empty.

tools. googleSearchRetrieval · object

Google Search retrieves the configuration.

tools. googleSearch · object

Google Search tool configuration.

tools. computerUse · object

Computer operating tool configuration.

tools. urlContext · object

URL context tool configuration.

tools. fileSearch · object

File search tool configuration.

tools. mcpServers · object[]

Connectable MCP server.

tools. googleMaps · object

Geolocation search tool configuration.

expireTime · string<date-time>

Absolute time of cache expiration, using RFC 3339 format. The server output will be normalized to UTC time. This field is mutually exclusive with ttl, at most one of them can be set.

Examples:

"2026-09-08T12:00:00Z"

"2026-09-08T12:00:00.123Z"

ttl · string

The relative validity period of the cache, in seconds, supports up to 9 decimal places, and ends with s. This field is for input only and is mutually exclusive with expireTime.

Pattern: ^[0-9]+(?:\.[0-9]{1,9})?s$

Examples:

"300s"

"3600s"

"3.5s"

displayName · string

A human-readable name set by the user for the cached content, containing up to 128 Unicode characters. This field cannot be modified after the cache is created.

Maximum string length: 128

systemInstruction · object

System commands set by the developer. Currently only plain text Parts are supported. This field is for input only and cannot be modified after the cache is created.

Hide child attributes

systemInstruction. parts · object[] · required

List of text parts that make up a system command.

Minimum array length: 1

Hide child attributes

systemInstruction.parts. text · string · required

System command text that defines a model's identity, behavior, task requirements, or output rules.

systemInstruction. role · enum<string>

The role of the system command content. This field can usually be omitted.

Available options: user, model

toolConfig · object

Tool call configuration. This configuration is shared by all tools and is only used for input. The cache cannot be modified after it is created.

Hide child attributes

toolConfig. functionCallingConfig · object

Function call behavior configuration.

Hide child attributes

toolConfig.functionCallingConfig. mode · enum<string> · default: AUTO

Function calling pattern. MODE_UNSPECIFIED means unspecified and not recommended; AUTO means the model can return text or call a function at its discretion; ANY means the model must call a function; NONE means function calls are prohibited; VALIDATED means the model can return text or call a constraint-validated function.

Available options: MODE_UNSPECIFIED, AUTO, ANY, NONE, VALIDATED

toolConfig.functionCallingConfig. allowedFunctionNames · string[]

A list of function names that the model is allowed to call. Should only be set when mode is ANY or VALIDATED, and the name must match the function name in functionDeclarations.

Minimum array length: 1

Function names that are allowed to be called.

toolConfig. retrievalConfig · object

Retrieves the context configuration used by the tool.

Hide child attributes

toolConfig.retrievalConfig. latLng · object

The latitude and longitude of the user's location follows the WGS84 coordinate standard.

Hide child attributes

toolConfig.retrievalConfig.latLng. latitude · number · required

Latitude in degrees, ranging from -90 to 90.

Required range: -90 <= x <= 90

toolConfig.retrievalConfig.latLng. longitude · number · required

Longitude in degrees, ranging from -180 to 180.

Required range: -180 <= x <= 180

toolConfig.retrievalConfig. languageCode · string

The language code used for user content should use BCP 47 language tags, such as zh-CN, en-US.

toolConfig. includeServerSideToolInvocations · boolean · default: false

Whether to include the server tool call and its response in the Content of the model response. After setting to true, the client can observe the calling process of the server tool.

Response

200 - application/json

The cached content resource returned after successful creation. The response mainly contains cache identification, model, creation time, update time, actual expiration time and token usage.

name · string · required

The unique resource name of cached content, generated by the server, in the format cachedContents/{id}.

Pattern: ^cachedContents/[^/]+$

Example:

"cachedContents/abc123def456"

model · string · required

The name of the model resource bound to this cache. Caching can only be used with this model.

Pattern: ^models/[^/]+$

Example:

"models/gemini-1.5-flash-001"

expireTime · string<date-time> · required

The absolute time at which the cache actually expires. Regardless of whether expireTime or ttl is used in the request, the server will return this field in the response.

Example:

"2026-09-08T11:00:00Z"

displayName · string

The human-readable name set when creating the cache. This field may not be returned when not set.

Maximum string length: 128

createTime · string<date-time>

The creation time of the cached resource, generated by the server, in RFC 3339 format and usually normalized to UTC time.

Example:

"2026-09-08T10:00:00Z"

updateTime · string<date-time>

The time when the cached resource was last updated, generated by the server, in RFC 3339 format and usually normalized to UTC time.

Example:

"2026-09-08T10:00:00Z"

usageMetadata · object

Token usage information for cached content.

Hide child attributes

usageMetadata. totalTokenCount · integer

The total number of tokens currently occupied by cached content.

Required range: x >= 0