El conteo de tokens te permite saber cuántos tokens de entrada usará una solicitud antes de enviarla al modelo. Úsalo para:
- Optimizar los prompts para que se ajusten a los límites de contexto
- Estimar los costos antes de hacer llamadas a la API
- Dirigir las solicitudes según su tamaño (por ejemplo, enviar los prompts más cortos a modelos más rápidos)
- Evitar sorpresas con las imágenes y los archivos sin tener que hacer estimaciones basadas en el número de caracteres
El punto de acceso para contar tokens de entrada acepta el mismo formato de entrada que la API de Responses. Envía texto, mensajes, imágenes, archivos, herramientas o conversaciones. La API devuelve el número exacto de tokens que recibirá el modelo.
El conteo incluye los tokens de formato que representan la estructura de la solicitud, como los roles de los mensajes y los límites entre ellos. Es posible que estos tokens no aparezcan en el texto ni en los campos que tokenizas localmente.
Los tokenizadores locales como tiktoken funcionan con texto plano, pero tienen algunas limitaciones:
- Imágenes y archivos: los tokenizadores locales no los admiten y las estimaciones como
characters / 4 son imprecisas
- Herramientas y esquemas: agregan tokens que son difíciles de contar localmente
- Comportamiento específico de cada modelo: funciones como el razonamiento o el almacenamiento en caché pueden cambiar la tokenización
La API de conteo de tokens tiene en cuenta todos estos casos. Envía los mismos datos que enviarías a responses.create para obtener un conteo exacto. Luego usa el resultado para validar mensajes o estimar costos.
1
2
3
4
5
6
7
8
9
10import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.inputTokens.count({
model: "gpt-6-astra",
input: "Tell me a joke.",
});
console.log(response.input_tokens);
1
2
3
4
5
6
7
8from openai import OpenAI
client = OpenAI()
response = client.responses.input_tokens.count(
model="gpt-6-astra", input="Tell me a joke."
)
print(response.input_tokens)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
Model: openai.String("gpt-6-astra"),
Input: responses.InputTokenCountParamsInputUnion{OfString: openai.String("Tell me a joke.")},
})
if err != nil {
panic(err)
}
fmt.Println(count.InputTokens)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.inputtokens.InputTokenCountParams;
var count =
client
.responses()
.inputTokens()
.count(
InputTokenCountParams.builder()
.model("gpt-6-astra")
.input("Tell me a joke.")
.build());
System.out.println(count.inputTokens());
1
2
3
4
5
6
7
8
9
10require "openai"
client = OpenAI::Client.new
count = client.responses.input_tokens.count(
model: "gpt-6-astra",
input: "Tell me a joke."
)
puts(count.input_tokens)
1
2
3
4
5
6
7curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-astra",
"input": "Tell me a joke."
}'
1
2
3
4
5openai responses:input-tokens count \
--model gpt-6-astra \
--input "Tell me a joke." \
--raw-output \
--transform input_tokens
1
2
3
4
5
6
7
8
9
10
11
12
13
14import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.inputTokens.count({
model: "gpt-6-astra",
input: [
{ role: "user", content: "What is 2 + 2?" },
{ role: "assistant", content: "2 + 2 equals 4." },
{ role: "user", content: "What about 3 + 3?" },
],
});
console.log(response.input_tokens);
1
2
3
4
5
6
7
8
9
10
11
12
13from openai import OpenAI
client = OpenAI()
response = client.responses.input_tokens.count(
model="gpt-6-astra",
input=[
{"role": "user", "content": "What is 2 + 2?"},
{"role": "assistant", "content": "2 + 2 equals 4."},
{"role": "user", "content": "What about 3 + 3?"},
],
)
print(response.input_tokens)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
input := []responses.ResponseInputItemUnionParam{
responses.ResponseInputItemParamOfMessage("What is 2 + 2?", responses.EasyInputMessageRoleUser),
responses.ResponseInputItemParamOfMessage("2 + 2 equals 4.", responses.EasyInputMessageRoleAssistant),
responses.ResponseInputItemParamOfMessage("What about 3 + 3?", responses.EasyInputMessageRoleUser),
}
count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
Model: openai.String("gpt-6-astra"),
Input: responses.InputTokenCountParamsInputUnion{OfResponseInputItemArray: input},
})
if err != nil {
panic(err)
}
fmt.Println(count.InputTokens)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.ResponseInputItem;
import com.openai.models.responses.inputtokens.InputTokenCountParams;
import java.util.List;
var count =
client
.responses()
.inputTokens()
.count(
InputTokenCountParams.builder()
.model("gpt-6-astra")
.inputOfResponseInputItems(
List.of(
ResponseInputItem.ofEasyInputMessage(
EasyInputMessage.builder()
.role(EasyInputMessage.Role.USER)
.content("What is 2 + 2?")
.build()),
ResponseInputItem.ofEasyInputMessage(
EasyInputMessage.builder()
.role(EasyInputMessage.Role.ASSISTANT)
.content("2 + 2 equals 4.")
.build()),
ResponseInputItem.ofEasyInputMessage(
EasyInputMessage.builder()
.role(EasyInputMessage.Role.USER)
.content("What about 3 + 3?")
.build())))
.build());
System.out.println(count.inputTokens());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24require "openai"
client = OpenAI::Client.new
conversation = [
{
role: :user,
content: "What is 2 + 2?"
},
{
role: :assistant,
content: "2 + 2 equals 4."
},
{
role: :user,
content: "What about 3 + 3?"
}
]
count = client.responses.input_tokens.count(
model: "gpt-6-astra",
input: conversation
)
puts(count.input_tokens)
1
2
3
4
5
6
7
8
9
10
11curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-astra",
"input": [
{"role": "user", "content": "What is 2 + 2?"},
{"role": "assistant", "content": "2 + 2 equals 4."},
{"role": "user", "content": "What about 3 + 3?"}
]
}'
1
2
3
4
5
6
7
8
9
10
11
12openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
model: gpt-6-astra
input:
- role: user
content: What is 2 + 2?
- role: assistant
content: 2 + 2 equals 4.
- role: user
content: What about 3 + 3?
YAML
1
2
3
4
5
6
7
8
9
10
11import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.inputTokens.count({
model: "gpt-6-astra",
instructions: "You are a helpful assistant that explains concepts simply.",
input: "Explain quantum computing in one sentence.",
});
console.log(response.input_tokens);
1
2
3
4
5
6
7
8
9
10from openai import OpenAI
client = OpenAI()
response = client.responses.input_tokens.count(
model="gpt-6-astra",
instructions="You are a helpful assistant that explains concepts simply.",
input="Explain quantum computing in one sentence.",
)
print(response.input_tokens)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
Model: openai.String("gpt-6-astra"),
Instructions: openai.String("You are a helpful assistant that explains concepts simply."),
Input: responses.InputTokenCountParamsInputUnion{OfString: openai.String("Explain quantum computing in one sentence.")},
})
if err != nil {
panic(err)
}
fmt.Println(count.InputTokens)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.inputtokens.InputTokenCountParams;
var count =
client
.responses()
.inputTokens()
.count(
InputTokenCountParams.builder()
.model("gpt-6-astra")
.input("Explain quantum computing in one sentence.")
.instructions("You are a helpful assistant that explains concepts simply.")
.build());
System.out.println(count.inputTokens());
1
2
3
4
5
6
7
8
9
10
11require "openai"
client = OpenAI::Client.new
count = client.responses.input_tokens.count(
model: "gpt-6-astra",
instructions: "You are a helpful assistant that explains concepts simply.",
input: "Explain quantum computing in one sentence."
)
puts(count.input_tokens)
1
2
3
4
5
6
7
8curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-astra",
"instructions": "You are a helpful assistant that explains concepts simply.",
"input": "Explain quantum computing in one sentence."
}'
1
2
3
4
5
6
7openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
model: gpt-6-astra
instructions: You are a helpful assistant that explains concepts simply.
input: Explain quantum computing in one sentence.
YAML
La cantidad de tokens que consume una imagen depende de su tamaño y nivel de detalle. La API de conteo de tokens devuelve la cantidad exacta sin necesidad de estimarla.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.inputTokens.count({
model: "gpt-6-astra",
input: [
{
role: "user",
content: [
{
type: "input_image",
image_url: "https://example.com/chart.png",
detail: "auto",
},
{ type: "input_text", text: "Summarize this chart." },
],
},
],
});
console.log(response.input_tokens);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21from openai import OpenAI
client = OpenAI()
# Use file_id from uploaded file, or image_url for a URL
response = client.responses.input_tokens.count(
model="gpt-6-astra",
input=[
{
"role": "user",
"content": [
{
"type": "input_image",
"image_url": "https://example.com/chart.png",
},
{"type": "input_text", "text": "Summarize this chart."},
],
}
],
)
print(response.input_tokens)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
input := []responses.ResponseInputItemUnionParam{
responses.ResponseInputItemParamOfMessage(
responses.ResponseInputMessageContentListParam{
{OfInputImage: &responses.ResponseInputImageParam{ImageURL: openai.String("https://example.com/chart.png"), Detail: responses.ResponseInputImageDetailAuto}},
{OfInputText: &responses.ResponseInputTextParam{Text: "Summarize this chart."}},
},
responses.EasyInputMessageRoleUser,
),
}
count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
Model: openai.String("gpt-6-astra"),
Input: responses.InputTokenCountParamsInputUnion{OfResponseInputItemArray: input},
})
if err != nil {
panic(err)
}
fmt.Println(count.InputTokens)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseInputImage;
import com.openai.models.responses.ResponseInputItem;
import com.openai.models.responses.inputtokens.InputTokenCountParams;
import java.util.List;
var count =
client
.responses()
.inputTokens()
.count(
InputTokenCountParams.builder()
.model("gpt-6-astra")
.inputOfResponseInputItems(
List.of(
ResponseInputItem.ofMessage(
ResponseInputItem.Message.builder()
.role(ResponseInputItem.Message.Role.USER)
.addContent(
ResponseInputImage.builder()
.detail(ResponseInputImage.Detail.AUTO)
.imageUrl(
"https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg")
.build())
.addInputTextContent("Summarize this chart.")
.build())))
.build());
System.out.println(count.inputTokens());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25require "openai"
client = OpenAI::Client.new
count = client.responses.input_tokens.count(
model: "gpt-6-astra",
input: [
{
role: :user,
content: [
{
type: :input_image,
image_url: "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg",
detail: :auto
},
{
type: :input_text,
text: "Summarize this chart."
}
]
}
]
)
puts(count.input_tokens)
1
2
3
4
5
6
7
8
9
10
11
12
13curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-astra",
"input": [{
"role": "user",
"content": [
{"type": "input_image", "image_url": "https://example.com/chart.png"},
{"type": "input_text", "text": "Summarize this chart."}
]
}]
}'
1
2
3
4
5
6
7
8
9
10
11
12openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
model: gpt-6-astra
input:
- role: user
content:
- type: input_image
image_url: https://example.com/chart.png
- type: input_text
text: Summarize this chart.
YAML
Puedes usar file_id (de la API de Files) o image_url (una URL o una URL de datos en base64). Para obtener más información, consulta la guía de imágenes y visión.
Las definiciones de herramientas (esquemas de funciones, servidores MCP, etc.) agregan tokens al contexto. Cuéntalos junto con los tokens de tu entrada:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.inputTokens.count({
model: "gpt-6-astra",
tools: [
{
type: "function",
name: "get_weather",
description: "Get the current weather in a location",
strict: true,
parameters: {
type: "object",
properties: { location: { type: "string" } },
required: ["location"],
additionalProperties: false,
},
},
],
input: "What is the weather in San Francisco?",
});
console.log(response.input_tokens);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21from openai import OpenAI
client = OpenAI()
response = client.responses.input_tokens.count(
model="gpt-6-astra",
tools=[
{
"type": "function",
"name": "get_weather",
"description": "Get the current weather in a location",
"parameters": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
}
],
input="What is the weather in San Francisco?",
)
print(response.input_tokens)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
parameters := map[string]any{
"type": "object",
"properties": map[string]any{
"location": map[string]any{"type": "string"},
},
"required": []string{"location"},
"additionalProperties": false,
}
tool := responses.ToolParamOfFunction("get_weather", parameters, true)
tool.OfFunction.Description = openai.String("Get the current weather in a location")
count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
Model: openai.String("gpt-6-astra"),
Input: responses.InputTokenCountParamsInputUnion{OfString: openai.String("What is the weather in San Francisco?")},
Tools: []responses.ToolUnionParam{tool},
})
if err != nil {
panic(err)
}
fmt.Println(count.InputTokens)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.inputtokens.InputTokenCountParams;
import java.util.List;
import java.util.Map;
var count =
client
.responses()
.inputTokens()
.count(
InputTokenCountParams.builder()
.model("gpt-6-astra")
.input("What is the weather in San Francisco?")
.addTool(
FunctionTool.builder()
.name("get_weather")
.description("Get the current weather in a location")
.strict(true)
.parameters(
FunctionTool.Parameters.builder()
.putAdditionalProperty("type", JsonValue.from("object"))
.putAdditionalProperty(
"properties",
JsonValue.from(
Map.of("location", Map.of("type", "string"))))
.putAdditionalProperty(
"required", JsonValue.from(List.of("location")))
.putAdditionalProperty(
"additionalProperties", JsonValue.from(false))
.build())
.build())
.build());
System.out.println(count.inputTokens());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24require "openai"
client = OpenAI::Client.new
count = client.responses.input_tokens.count(
model: "gpt-6-astra",
input: "What is the weather in San Francisco?",
tools: [
{
type: :function,
name: "get_weather",
description: "Get the current weather in a location",
strict: true,
parameters: {
type: "object",
properties: { location: { type: "string" } },
required: ["location"],
additionalProperties: false
}
}
]
)
puts(count.input_tokens)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-astra",
"tools": [{
"type": "function",
"name": "get_weather",
"description": "Get the current weather in a location",
"parameters": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"]
}
}],
"input": "What is the weather in San Francisco?"
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
model: gpt-6-astra
tools:
- type: function
name: get_weather
description: Get the current weather in a location
parameters:
type: object
properties:
location:
type: string
required:
- location
input: What is the weather in San Francisco?
YAML
La API admite archivos como entrada (por el momento, solo PDF). Envía file_id, file_url o file_data como lo harías con responses.create. El conteo de tokens refleja toda la entrada que procesa el modelo.
El uso de tokens de salida que informa la API incluye todos los tokens que genera el modelo, incluso los que no aparecen en el texto visible de la respuesta. La API de Responses informa este total en output_tokens y la API para completar chats lo informa en completion_tokens.
Algunos modelos, entre ellos los de la familia GPT-5, generan tokens para dar formato a los canales de respuesta, las llamadas a herramientas y otros elementos de la estructura del mensaje, o para delimitarlos. Estos tokens de formato no aparecen en el contenido del mensaje ni en logprobs, y el informe de uso no siempre los desglosa por separado. Por eso, el total de tokens de salida que informa cada API puede superar la cantidad de tokens visibles o la de tokens incluidos en logprobs, incluso cuando el valor informado de reasoning_tokens es 0.
Los parámetros max_output_tokens y max_completion_tokens limitan el total de tokens que genera el modelo, incluidos los que no son visibles. La cantidad de tokens no visibles varía según el modelo y la estructura de la respuesta, así que no supongas que la diferencia entre el uso informado y la salida visible es fija. Deja un margen al configurar estos límites cuando necesites una cantidad específica de salida visible.
Para ver todos los parámetros y la estructura de la respuesta, consulta la referencia de la API para contar tokens de entrada. El punto de acceso es:
POST /v1/responses/input_tokens
La respuesta incluye input_tokens (un número entero) y object: "response.input_tokens".