Text
Grok 4.7
네이티브 Chat Completions, Responses, Messages 형식으로 Grok 4.7을 호출합니다. 파라미터, 스트리밍, 사용량과 현재 기능 제한을 안내합니다.
아래 세 가지 형식 중 하나로 grok-4.7을 사용합니다. 인증에는 SeedRouter API 키를 사용합니다. 모델 페이지에서 Playground와 현재 토큰 요금을 확인하고, 요금 안내에서 캐시된 입력과 추론의 계산 방법을 알아볼 수 있습니다.
빠른 시작
curl https://api.seedrouter.ai/v1/responses \
-H "Authorization: Bearer $SEEDROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"grok-4.7","input":"What is 2 + 2?","reasoning":{"effort":"low"},"max_output_tokens":64,"store":false}'JSON 응답에는 output 항목과 usage가 포함됩니다. 대화 기록을 구성할 때는 추론 및 도구 항목을 포함한 모든 출력 항목을 유지합니다.
요청 형식
| 형식 | 엔드포인트 | 필수 필드 |
|---|---|---|
| Responses | POST /v1/responses | model, input |
| Chat Completions | POST /v1/chat/completions | model, messages |
| Messages | POST /v1/messages | model, messages, max_tokens |
Content-Type: application/json과 Authorization: Bearer $SEEDROUTER_API_KEY를 사용합니다. Messages 클라이언트는 anthropic-version: 2023-06-01도 전송할 수 있습니다.
파라미터와 제약 조건
OpenAPI 명세에 중첩된 요청 및 응답 스키마 전체가 포함되어 있습니다. 아래 표는 지원하는 모든 최상위 요청 필드를 나열합니다. 알 수 없는 필드와 이 모델이 공식적으로 무시하는 파라미터는 제거됩니다. 지원하는 파라미터라도 값이 잘못되면 여전히 유효하지 않습니다.
선택 사항이며 null을 허용하는 필드에는 명시적으로 null을 지정할 수 있습니다. 필드를 생략하면 API 기본값을 사용합니다. Playground는 user를 숨기고 model을 grok-4.7로 고정합니다. API 클라이언트는 계속 user를 전송할 수 있습니다.
- 컨텍스트: 대화와 출력을 포함하여 500,000 토큰입니다.
- 추론 강도:
low,medium,high,xhigh이며 기본값은high입니다. max_completion_tokens와max_output_tokens의 기본값은 표시되는 출력 토큰 128,000개입니다. 추론 및 함수 호출 토큰은 이 표시 출력 한도에 포함되지 않습니다. 이는 기본값이며 최대 출력 능력을 의미하지 않습니다.- 출력 한도는 양의 정수여야 합니다. API는 기존 정수 안전 상한인 1,073,741,823도 적용하며, 컨텍스트 용량 제한은 계속 적용됩니다.
temperature: 0 이상 2 이하, 기본값 1입니다.top_p: 0보다 크고 1 이하, 기본값 1입니다. Responses의min_p: 0 이상 1 이하이며,top_k는 1 이상의 정수입니다.- 도구 정의는 최대 350개입니다.
stream_options를 사용하려면stream: true가 필요합니다. instructions와previous_response_id는 함께 사용할 수 없습니다. 추론 요약은 항상 상세 모드입니다.
Responses 파라미터
| 필드 | 유형 | 규칙 |
|---|---|---|
include | 배열 또는 null | 응답에 추가로 포함할 필드의 배열입니다. |
input(필수) | 객체 또는 다른 지원 유형 | 텍스트 문자열 또는 전체 입력 항목 배열입니다. |
instructions | 문자열 또는 null | 시스템 지침입니다. previous_response_id와 함께 사용할 수 없습니다. |
max_output_tokens | 정수 또는 null | 표시되는 출력의 한도이며 기본값은 128,000입니다. |
max_turns | 정수 또는 null | 에이전트의 최대 턴 수를 정수로 지정합니다. |
min_p | 숫자 또는 null | 0 이상 1 이하의 숫자입니다. |
model(필수) | 문자열 | grok-4.7로 고정합니다. |
parallel_tool_calls | 불리언 또는 null | 불리언이며 기본값은 true입니다. |
previous_response_id | 문자열 또는 null | 문자열 형식의 응답 ID입니다. 현재 ID로 대화를 이어갈 수 없습니다. |
prompt_cache_key | 문자열 또는 null | 문자열 형식의 캐시 키입니다. |
reasoning | 객체 | 추론 설정이며 강도의 기본값은 high입니다. |
reasoning_effort | 문자열 또는 null | low, medium, high, xhigh이며 기본값은 high입니다. |
safety_identifier | 문자열 또는 null | 호출자가 제공하는 선택적 안전 식별자입니다. |
search_parameters | 객체 | 검색 설정입니다. |
service_tier | 문자열 | auto, default, priority, fast입니다. priority와 fast는 토큰 단가가 두 배입니다. |
store | 불리언 또는 null | 불리언이며 기본값은 true입니다. 저장된 응답에 대한 작업은 현재 사용할 수 없습니다. |
stream | 불리언 또는 null | 불리언이며 기본값은 false입니다. |
temperature | 숫자 또는 null | 0 이상 2 이하의 숫자이며 기본값은 1입니다. |
text | 객체 | format을 포함한 텍스트 응답 설정입니다. |
tool_choice | 객체 또는 다른 지원 유형 | 자동, 비활성화, 필수 호출 또는 지정한 도구입니다. 구문은 형식에 따라 다릅니다. |
tools | 배열 또는 null | 도구 정의이며 최대 350개입니다. |
top_k | 정수 또는 null | 정수이며 Responses에서는 1 이상이어야 합니다. |
top_p | 숫자 또는 null | 0보다 크고 1 이하인 숫자이며 기본값은 1입니다. |
user | 문자열 또는 null | 호출자가 제공하는 선택적 식별자이며 Playground에서는 숨겨집니다. |
Chat Completions 파라미터
| 필드 | 유형 | 규칙 |
|---|---|---|
deferred | 불리언 또는 null | 불리언이며 기본값은 false입니다. 지연 완료는 현재 사용할 수 없습니다. |
max_completion_tokens | 정수 또는 null | 표시되는 출력의 한도이며 기본값은 128,000입니다. |
max_tokens | 정수 또는 null | 표시되는 출력의 양수 한도입니다. Messages에서는 필수입니다. |
messages(필수) | 배열 | 해당 형식의 대화 메시지입니다. |
model(필수) | 문자열 | grok-4.7로 고정합니다. |
n | 정수 또는 null | 1 이상의 정수이며 기본값은 1입니다. |
parallel_tool_calls | 불리언 또는 null | 불리언이며 기본값은 true입니다. |
prompt_cache_key | 문자열 또는 null | 문자열 형식의 캐시 키입니다. |
reasoning_effort | 문자열 또는 null | low, medium, high, xhigh이며 기본값은 high입니다. |
response_format | 객체 또는 다른 지원 유형 | 텍스트, JSON 객체 또는 JSON 스키마 출력입니다. |
safety_identifier | 문자열 또는 null | 호출자가 제공하는 선택적 안전 식별자입니다. |
search_parameters | 객체 | 검색 설정입니다. |
seed | 정수 또는 null | 정수 형식의 샘플링 시드입니다. |
service_tier | 문자열 | auto, default, priority, fast입니다. priority와 fast는 토큰 단가가 두 배입니다. |
stream | 불리언 또는 null | 불리언이며 기본값은 false입니다. |
stream_options | 객체 | 스트리밍 옵션이며 stream: true가 필요합니다. |
temperature | 숫자 또는 null | 0 이상 2 이하의 숫자이며 기본값은 1입니다. |
tool_choice | 객체 또는 다른 지원 유형 | 자동, 비활성화, 필수 호출 또는 지정한 도구입니다. 구문은 형식에 따라 다릅니다. |
tools | 배열 또는 null | 도구 정의이며 최대 350개입니다. |
top_p | 숫자 또는 null | 0보다 크고 1 이하인 숫자이며 기본값은 1입니다. |
user | 문자열 또는 null | 호출자가 제공하는 선택적 식별자이며 Playground에서는 숨겨집니다. |
web_search_options | 객체 | 호환 형식의 검색 옵션입니다. |
Messages 파라미터
| 필드 | 유형 | 규칙 |
|---|---|---|
max_tokens(필수) | 정수 | 표시되는 출력의 양수 한도입니다. Messages에서는 필수입니다. |
messages(필수) | 배열 | 해당 형식의 대화 메시지입니다. |
metadata | 객체 | Messages 메타데이터 객체입니다. |
model(필수) | 문자열 | grok-4.7로 고정합니다. |
stop_sequences | 배열 또는 null | 중지 문자열의 배열입니다. |
stream | 불리언 또는 null | 불리언이며 기본값은 false입니다. |
system | 객체 또는 다른 지원 유형 | 시스템 문자열 또는 콘텐츠 블록입니다. |
temperature | 숫자 또는 null | 0 이상 2 이하의 숫자이며 기본값은 1입니다. |
tool_choice | 객체 또는 다른 지원 유형 | 자동, 비활성화, 필수 호출 또는 지정한 도구입니다. 구문은 형식에 따라 다릅니다. |
tools | 배열 또는 null | 도구 정의이며 최대 350개입니다. |
top_k | 정수 또는 null | 정수이며 Responses에서는 1 이상이어야 합니다. |
top_p | 숫자 또는 null | 0보다 크고 1 이하인 숫자이며 기본값은 1입니다. |
스트리밍
stream을 true로 설정합니다. Chat은 completion 청크를, Responses는 이름이 지정된 응답 이벤트를, Messages는 메시지 및 콘텐츠 블록 이벤트를 전송합니다. 텍스트 델타뿐 아니라 최종 사용량 이벤트도 읽어야 합니다. 도구 호출과 추론은 별도의 출력 항목일 수 있으므로, 기록을 보존할 때 스트림에서 표시되는 텍스트만 남기지 마세요.
{
"model": "grok-4.7",
"input": "Explain a mutex in one sentence.",
"reasoning": { "effort": "low" },
"max_output_tokens": 128,
"store": false,
"stream": true
}도구와 구조화된 출력
선택한 형식에 맞는 도구 정의를 사용합니다. Chat은 response_format을, Responses는 text.format을 사용합니다. 이 모델로 함수, 웹 검색, X 검색, 코드 인터프리터와 MCP 호출을 실제 검증했습니다. Shell은 클라이언트에서 실행할 호출을 반환하며, 컴퓨터에서 명령을 자동 실행하지 않습니다. 전체 스키마에는 다른 도구 유형도 설명되어 있지만, 스키마에 항목이 있다는 사실만으로 특정 외부 서비스가 설정되었다고 볼 수는 없습니다.
{
"model": "grok-4.7",
"input": "Use the code interpreter once to compute 13*17. Return the number.",
"tools": [{ "type": "code_interpreter" }],
"tool_choice": "required",
"max_turns": 1,
"reasoning": { "effort": "low" },
"max_output_tokens": 32,
"store": false
}도구 사용량은 토큰과 별도로 청구됩니다. 웹 검색과 코드 인터프리터는 호출 횟수를 기준으로 합니다. X 검색은 가져온 게시물과 프로필 수를 기준으로 하며, 반복해서 가져온 항목도 포함합니다. X 검색 호출 횟수는 청구 단위가 아닙니다. usage.server_side_tool_usage_details와 계정 사용량 기록을 확인하세요.
사용량과 요금
요금은 전체 입력 길이에 따라 달라집니다. 입력이 200,000 토큰 미만이면 표준 구간을 적용합니다. 200,000 토큰 이상이면 요청 전체에 긴 컨텍스트 구간을 적용하며, 구간 선택 시 캐시된 입력도 포함합니다. service_tier: "priority"와 "fast"는 두 구간 모두에서 토큰 단가를 두 배로 적용합니다. auto와 default는 표준 서비스를 선택합니다. 도구 요금은 별도로 계산하며, 이 토큰 배수로 인해 두 배가 되지는 않습니다.
| 형식 | 입력 계산 | 출력 계산 |
|---|---|---|
| Responses | input_tokens에 input_tokens_details.cached_tokens가 포함됩니다 | output_tokens에 추론이 포함되므로 추론 내역을 다시 더하지 않습니다 |
| Chat | prompt_tokens에 prompt_tokens_details.cached_tokens가 포함됩니다 | xAI는 표시되는 completion_tokens를 별도로 보고합니다. 청구 대상 출력 합계는 추론을 포함한 total_tokens - prompt_tokens입니다 |
| Messages | input_tokens에 cache_read_input_tokens가 포함되지 않으므로 캐시 필드를 더해 전체 입력을 구합니다 | output_tokens가 출력 합계입니다 |
공개 응답에는 사용량 카운터가 포함되며 금액 필드는 포함되지 않습니다. 최종 요금은 사용량 기록에서 확인할 수 있습니다. 실패한 요청에는 요금이 부과되지 않습니다.
대화 기록과 현재 제한
상태를 저장하지 않고 대화를 이어가려면 이전 입력, 반환된 모든 출력 항목, 다음 사용자 메시지를 새로운 input으로 보냅니다. Chat 또는 Messages에서는 해당 형식의 전체 메시지 기록을 보냅니다. 암호화된 추론 및 도구 항목이 반환되면 변경하지 않고 보존합니다.
현재 서비스에서는 previous_response_id로 대화를 이어가거나, 저장된 응답을 조회·삭제하거나, 저장된 입력 항목 목록을 조회하거나, 지연 완료된 Chat 응답을 반환할 수 없습니다. 생성 시 store: true가 허용될 수 있지만, 이것이 응답 저장 또는 조회 지원을 입증하지는 않습니다. 해당 필드는 공식 계약과 Playground에 그대로 남아 있으며, 현재 제한이 본래 동작의 정의를 대체하지는 않습니다.
파일 첨부는 테스트한 인라인 텍스트 및 PDF URL 입력에서 작동하지 않았습니다. 이미지 생성 요청은 이미지 없이 텍스트를 반환했고, 도구 검색은 서버 측 탐색을 완료하지 못했습니다. 이러한 기능은 사용 가능한 것으로 검증되지 않았습니다. Collections 검색에도 유효한 collection 리소스가 필요하며, 아직 검증되지 않았습니다.
Chat은 frequency_penalty, presence_penalty, logit_bias, stop, logprobs, top_logprobs를 무시합니다. Responses는 background, context_management, metadata, truncation, logprobs, top_logprobs를 무시합니다. 이 필드는 전달되지 않으며 활성 컨트롤로도 제공되지 않습니다.
오류
잘못된 요청은 완성된 답변 대신 오류를 반환합니다. 필드 값과 공개 오류 안내를 확인하세요. 오류를 반환한 요청에는 요금이 부과되지 않습니다.